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Preface 



The OpenBoot Command Reference manual describes the OpenBoot™ firmware 
that is part of the boot PROM in Sun™ systems. 

Audience 

The features of the OpenBoot firmware allow it to be used by end users as well 
as by system administrators and developers. This manual is for all such users 
who want to use the OpenBoot firmware to configure and debug their systems. 

Contents 

In this manual, you will find information on how to use the OpenBoot 
firmware to perform tasks such as: 

• Booting the operating system 

• Running diagnostics 

• Modifying system start-up configuration parameters 

• Loading and executing programs 

• Troubleshooting 

If you want to write Forth programs or if you want to use the more advanced 
features of this firmware (such as its debugging capabilities), this manual also 
describes the commands of the OpenBoot Forth Interpreter. 



XV 



Assumptions 



This manual assumes that you are working on a SPARC® system with a 
version 2.x OpenBoot PROM. Some of the tools and capabilities described in 
this manual do not exist on the pre-2.x PROM SPARC systems. If you are using 
a SPARCstation™ 1, SPARCstation IPC, or other system with a pre-2.x version 
PROM, refer to an earlier version of this manual: Open Boot PROM Toolkit 
User's Guide, part number 800-5279-10. Also see Appendix C in this manual for 
a list of unsupported commands. 

Organization 

The OpenBoot Command Reference is organized as follows: 

Chapter 1, "Overview," describes the user interface and other main features of 
the firmware. 

Chapter 2, "Booting and Testing Your System," explains the most common 
tasks for which the OpenBoot firmware is used. 

Chapter 3, "Setting Configuration Parameters," details how to perform system 
administration tasks with NVRAM parameters. 

Chapter 4, "Using Forth Tools," describes both basic and advanced functions of 
the OpenBoot Forth language. 

Chapter 5, "Loading and Executing Programs," describes how to load and 
execute programs from various sources (such as Ethernet, disk, or a serial 
port). 

Chapter 6, "Debugging," describes the firmware's debugging capabilities, 
including the Disassembler, the Forth Source-level Debugger, and breakpoints. 

Appendix A, "Setting Up a TIP Connection," describes how to connect your 
system to another Sun system using serial ports. 

Appendix B, "Building A Bootable Floppy Disk," tells you how to create a 
bootable floppy diskette from which you can load programs or files. 

Appendix C, "Unsupported Commands," lists commands that may not be 
available in earlier OpenBoot systems and possible workarounds for them. 
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Appendix D, "Troubleshooting Guide," discusses solutions for typical 
situations where you cannot boot the operating system. 

Appendix E, "Forth Word Reference," contains all currently-supported 
OpenBoot Forth commands. 

Related Documentation 

• A companion document to this manual is: 

• OpenBoot Quick Reference, part number 800-5675-11. 

This fold-out card is a summary of often-used OpenBoot Forth commands. 

• For information on FCode, the version of Forth implemented in the 
OpenBoot firmware for using SBus cards, refer to the Sun manuals: 

• Writing FCode Programs, part number 801-7050-10. 

• Writing FCode Programs for SBus Cards, part number 800-4456-10. 

• For more information on the Forth language, read: 

• Starting Forth 

Leo Bro die /Forth, Inc. 

Prentice-Hall Software Series 

Englewood Cliffs, New Jersey 07632 
The second edition of Starting Forth describes the current Forth standard 
dialect, Forth 83. 



Note - There are several differences between the versions of Forth described in 
the above document and the version described in this manual. Specifically, the 
boot PROM Forth Monitor uses 32-bit numbers instead of 16-bit numbers. 
Also, the text editor described in the referenced book is not the same as the 
Forth Monitor editor. 
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What Typographic Changes and Symbols Mean 



The following table describes the type changes and symbols used in this book. 
Table P-l Typographic Conventions 



Typeface or 
Symbol 


Meaning 


Example 


AaBbCcl23 


The names of commands, files, and directories; on-screen 
computer output 


Edit your . login file. 
Use Is -a to list all files. 

system% You have mail. 


AaBbCcl23 


What you type, contrasted with on-screen computer 
output 


system% su 
Password : 


AaBbCcl23 


Command-line placeholder: replace with a real name or 
value 


To delete a file, type rm filename . 


AaBbCcl23 


Book titles, new words or terms, or words to be 
emphasized 


Read Chapter 6 in User's Guide . 
These are called class options. 
You must be root to do this. 


Code samples are included in boxes and may display the following: 


ok 


The OpenBoot Forth Monitor prompt 


ok 


> 


The OpenBoot Restricted Monitor prompt 


> 


a. 
o 


UNIX C shell prompt 


system% 


$ 


UNIX Bourne and Korn shell prompt 


system$ 


# 


Superuser prompt, all shells 


system! 



• Keys are indicated by their name. For example: 

Press the Return key. 

• When you see two keys named, press and hold the first key down and then 
press the second key. For example: 

To press Control-D, press and hold Control, then press D. 

• In a command line, square brackets indicate an optional entry and italics 
indicate an argument that you must replace with the appropriate text. 
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Overview 



This chapter introduces the OpenBoot firmware, which is the standard 
firmware for Sun systems. 

The OpenBoot Version 1 firmware was introduced on the Sun SPARCstation 1. 
It also was the firmware for the SPARCstation 1+, SPARCstation IPC, and 
SPARCstation SLC systems. This manual describes Version 2 of the firmware, 
which first appeared on the SPARCstation 2 system. 

The OpenBoot firmware is stored in the boot PROM (programmable read-only 
memory) of a system so that it is executed immediately after you turn on your 
system. The primary task of the OpenBoot firmware is to boot the operating 
system from either a mass storage device or from a network. The firmware also 
provides extensive features for testing hardware and software interactively. 

Features of OpenBoot 

The OpenBoot architecture provides a significant increase in functionality over 
the boot PROMs in earlier Sun systems. Although this architecture was first 
implemented on SPARC systems, its design is processor-independent. Some 
notable features of the OpenBoot firmware include: 

• Plug-in device drivers. A plug- in device driver is usually loaded from a 
plug-in device such as an SBus card. The plug-in device driver can be used 
to boot the operating system from that device or to display text on the 
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device before the operating system has activated its own drivers. This 
feature allows the input and output devices supported by a particular 
system to evolve without changing the system PROM. 

• FCode interpreter. Plug-in drivers are written in a machine-independent 
interpreted language called FCode. Each OpenBoot system PROM contains 
an FCode interpreter. Thus, the same device and driver can be used on 
machines with different CPU instruction sets. 

• Device tree. The device tree is an OpenBoot data structure describing the 
devices (permanently installed and plug-in) attached to a system. Both the 
user and the operating system can determine the hardware configuration of 
the system by inspecting the device tree. 

• Programmable user interface. The OpenBoot user interface is based on the 
interactive programming language Forth. Sequences of user commands can 
be combined to form complete programs, and this provides a powerful 
capability for debugging hardware and software. 

The User Interface 

You can enter the OpenBoot environment in the following ways: 

• By halting the operating system. 

• By using the Stop-A key sequence from the keyboard. (This abruptly breaks 
execution of the operating system and should be used with caution.) 

• By power-cycling the system. (If your system is configured to boot 
automatically, you can enter the OpenBoot environment by pressing 
Stop-A after the display console banner appears but before the system 
starts booting the operating system. If automatic booting is not enabled, the 
system will enter the OpenBoot environment on its own instead of booting 
the operating system.) 

• When the system hardware detects an error from which it cannot recover. 
(This is known as a Watchdog Reset.) 

The OpenBoot firmware provides three external interfaces: an interface for the 
operating system or other standalone programs, an interface for expansion bus 
plug-in boards (for example, SBus), and a command line interface for the user 
at the system console. This manual describes the third of these interfaces: the 
system console command line interface. 



2 



OpenBoot Command Reference — August 1994 



The command line interface has two modes: 



• The Restricted Monitor 

• The Forth Monitor 

The Restricted Monitor 

The Restricted Monitor provides a simple set of commands to initiate booting 
of the system, resume system execution, or enter the Forth Monitor. The 
Restricted Monitor is also used to implement system security. (See Chapter 3, 
"Setting Configuration Parameters," for information on system security.) 

The Restricted Monitor prompt is >. When you enter the Restricted Monitor, 
the following screen is displayed: 



Type b (boot), c (continue), or n (new command mode) 

> 



The Restricted Monitor commands are summarized in Table 1-1. 



Table 1-1 Restricted Monitor Commands 



Command 


Description 


b [specifiers] 


Boot the operating system. 


c 


Resume the execution of a halted program. 


n 


Enter the Forth Monitor. 



The Forth Monitor 

The Restricted Monitor functions b (for booting the system) and c (for 
resuming execution of a halted program) are available as the boot (see 
Chapter 2, "Booting and Testing Your System,") and go (see Chapter 5, 
"Loading and Executing Programs,") commands, respectively, in the Forth 
Monitor. 

The Forth Monitor is an interactive command interpreter that gives you access 
to an extensive set of functions for hardware and software development, fault 
isolation, and debugging. A variety of system users, ranging from end-users to 
system administrators to system developers, can use these functions. 
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The Forth Monitor prompt is ok. When you enter the Forth Monitor, the 
following screen is displayed: 



Type help for more information 
ok 



The Default Mode 

The default mode in early OpenBoot systems is the Restricted Monitor. This 
was done mainly to provide a default look and feel similar to pre-OpenBoot 
systems. 

The SPARCserver™ 690 system was the first to have the Forth Monitor as the 
default mode. All systems introduced thereafter also default to this mode. For 
such systems, the Restricted Monitor's only real function is to support system 
security. (Chapter 3, "Setting Configuration Parameters," discusses system 
security.) 

If you want to leave the Forth Monitor and get into the Restricted Monitor, 
type: 



ok old-mode 



The Device Tree 

Devices are attached to a SPARC-based system on a set of interconnected 
buses. The OpenBoot firmware represents the interconnected buses and their 
attached devices as a tree of nodes. Such a tree is called the device tree. A node 
representing the whole machine forms the tree's root node. 

Each device node can have: 

• Properties, which are the data structures describing the node and its 
associated device 

• Methods, which are the software procedures used to access the device 

• Children, which are other device nodes "attached" to that node and that lie 
directly below it in the device tree 

• A parent, which is the node that lies directly above it in the device tree. 



4 



OpenBoot Command Reference — August 1994 



Nodes with children usually represent buses and their associated controllers, if 
any. Each such node defines a physical address space that distinguishes the 
devices connected to the node from one another. Each child of that node is 
assigned a physical address within the parent's address space. 

The physical address generally represents a physical characteristic unique to 
the device (such as the bus address or the slot number where the device is 
installed). This prevents device addresses from changing when another device 
is installed in the system. 

Device Path Names, Addresses, and Arguments 

The firmware deals directly with hardware devices in the system. Each device 
has a unique name representing the type of device and where that device is 
located within the system addressing structure. The following example shows 
a full device path name: 

/sbus@l, f8000000/esp@0, 40000/sd@3,0:a 

A full device path name is a series of node names separated by slashes (/). The 
root of the tree is the machine node, which is not named explicitly but is 
indicated by a leading slash (/). Each node name has the form: 

name@address:arguments 

Table 1-2 describes each of these parameters. 



Table 1-2 Device Path Name Parameters 



Path Name Parameter 


Description 


name 


A text string that, ideally, has some mnemonic value. (For example, sd represents "SCSI disk".) 
Many names, especially names of plug-in modules, include the name or stock symbol of the 
device's manufacturer (for example, SUNW, esp). 


@ 


Must precede the address parameter. 


address 


A text string representing an address, usually of the form hex_number ,hex_number. (Numbers 
are given in hexadecimal format.) 




Must precede the arguments parameter. 


arguments 


A text string, whose format depends on the particular device. It can be used to pass additional 
information to the device's software. 
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The full device path name mimics the hardware addressing used by the system 
to distinguish between different devices. Thus, you can specify a particular 
device without ambiguity. 

In general, the address part of a node name represents an address in the address 
space of its parent. The exact meaning of a particular address depends on the 
bus to which the device is attached. Consider the same example: 

/sbus@l, f8000000/esp@0, 40000/sd@3,0:a 

• l,f8000000 represents an address on the main system bus, because the 
SBus interface is directly attached to the main system bus. 

• 0,40000 is an SBus slot number and an offset within that slot, because the 
esp device is in SBus slot 0 at offset 40000. (In this example, the device is a 
SCSI host adapter, although the name does not say so directly.) 

• 3, 0 is a SCSI target and logical unit number, because the sd device is 
attached to a SCSI bus at target 3, logical unit 0. 

When specifying a path name, either the ©address or name part of a node name 
is optional, in which case the firmware tries to pick the device that best 
matches the given name. If more than one equally-good choice exists, the 
firmware makes a choice (but it may not be the one you want). 

For example, using /sbus/esp@0, 40000/sd@3, 0 assumes that the system in 
question has exactly one SBus interface on the main system bus, making sbus 
as unambiguous an address as sbus@l,f8000000. On the same system, 
however, /sbus/esp/sd@3, 0 might or might not be ambiguous. Since SBus 
accepts plug-in cards, there could be more than one esp device on the same 
SBus. If there were more than one on the system, using esp alone would not 
specify which one, and the firmware might not choose the one you intended. 

As another example, / sbus / @0,40000/sd@3,0 would normally be 
acceptable while /sbus/esp@0, 40000/03,0 usually would not, since both a 
SCSI disk device driver (sd) and a SCSI tape device driver (st) can use the 
SCSI target,logical unit address 3,0. 
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The arguments part of the node name is also optional. Once again, in the 
example: 

/sbus@l, f 8000000/esp@0, 4 0000/sd@3, 0 : a 

the argument for the sd device is the string a. The software driver for sd 
interprets its argument as a disk partition, so the device path name refers to 
partition a on that disk. 

Device Aliases 

There are two kinds of device names: 

• Full device path names (discussed in the previous section), such as 

/sbus@l, f8000000/esp@0, 40000/sd@3,0:a 

• Device aliases, such as disk 

A device alias, or simply, alias, is a shorthand representation of a device path 
name. An alias represents an entire device path name, not a component of it. For 
example, the alias disk may represent the device path name: 

/sbusgl, f 8000000/espgO, 4 0000/sd@3, 0 :a 

Systems have predefined device aliases for most commonly-used devices, so 
you rarely need to type a full device path name. 

Table 1-3 describes the devalias command, which is used to examine, create, 
and change aliases. 



Table 1-3 Examining and Creating Device Aliases 



Command 


Description 


devalias 


Display all current device aliases. 


devalias alias 


Display the device path name corresponding to alias. 


devalias alias device-path 


Define an alias representing device path. 

If an alias with the same name already exists, the new value supersedes the old. 



User-defined aliases are lost after a system reset or power cycle. If you want to 
create permanent aliases, you can either manually store the output of the 
devalias command in a portion of non- volatile RAM (NVRAM) called 
NVRAMRC, or use the nvalias and nvunalias commands. (See Chapter 3, 
"Setting Configuration Parameters," for more details.) 
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Displaying the Device Tree 



You can browse the device tree to examine and modify individual device tree 
nodes. The device tree browsing commands are similar to the UNIX® 
commands for changing the working directory within the UNIX directory tree. 
Selecting a device node makes it the current node. 

Examine the device tree with the commands shown in Table 1-4. 

Table 1-4 Commands for Browsing the Device Tree 



Command 


Description 


. attributes 


Display the names and values of the current node's properties. 


cd device-path 


Select the indicated device node, making it the current node. 


cd node-name 


Search for a node with the given name in the subtree below the current node, and select 
the first such node found. 


cd . . 


Select the device node that is the parent of the current node. 


cd / 


Select the root machine node. 


device-end 


De-select the current device node, leaving no node selected. 


Is 


Display the names of the current node's children. 


pwd 


Display the device path name that names the current node. 


show-devs [device-path] 


Display all the devices known to the system directly beneath a given level in the device 
hierarchy, show-devs used by itself shows the entire device tree. 


words 


Display the names of the current node's methods. 



If you have been browsing the device tree, and want to reset the system, type: 



ok device-end 
ok reset 
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The following example shows the use of . attributes: 



ok cd /zs@l,f 0000000 






ok . attributes 






address 


f fee9000 




port-b-ignore-cd 






port-a-ignore-cd 






keyboard 






device_type 


serial 




slave 


00000001 




intr 


0000000c 


00000000 


interrupts 


0000000c 




reg 


00000001 


fOOOOOOO 00000008 


name 


zs 




ok 







show-devs lists all the devices in the OpenBoot device tree, as shown in the 
following example: 



ok show-devs 

/fd@l, f 7200000 
/virtual-memory@0, 0 
/memoryOO, 0 
/sbusOl, f 8000000 
/auxiliary-io@l, f 7400003 
/interrupt-enableOl, f 5000000 
/memory-errorOl, f 4000000 
/counter-timergl, f 3000000 
/eepromOl, f 2000000 
/audio@l, f7201000 
/zsOl, fOOOOOOO 
/zsOl, f 1000000 
/openprom 
/aliases 
/ options 
/ packages 

/sbusOl, f 80 00000 /cgsix@3, 0 
/sbus@l, f8000000/le@0,c00000 
/sbusOl, f 80 00000 /esp@0, 8000 00 
ok 
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The following is an example of the use of words: 



ok cd /zs 








ok words 








self test 


ring-bell 


read 


remove-abort ? 


install-abort 


close 


open 


abort? restore 


clear 


reset 


initkbdmouse 


keyboard-addr mouse 


1200baud 


setbaud 


initport 


port-addr 


ok 









Getting Help 


Whenever you see the ok prompt on the display, you can ask the system for 
help by typing one of the help commands shown in Table 1-5. 

Table 1-5 Help Commands 


Command 


Description 


help 


List main help categories. 


help category 


Show help for all commands in the category. Use only the first word of the category 
description. 


help command 


Show help for individual command (where available). 



help, without any specifier, displays instructions on how to use the help 
system and lists the available help categories. Because of the large number of 
commands, help is available only for commands that are used frequently. 

If you want to see the help messages for all the commands in a selected 
category, or, possibly, a list of sub-categories, type: 



ok help category 



If you want help for a specific command, type: 



ok help command 
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For example, when you ask for information on the dump command, you see the 
following message: 



ok help dump 

Category: Memory access 

dump ( addr length -- ) display memory at addr for length bytes 
ok 



The above help message first shows that dump is a command from the Memory 
access category. The message also shows the format of the command. 



Note - In some newer systems, descriptions of additional machine-specific 
commands are available with the help command. 



A Caution About Using Some OpenBoot Commands 

If you boot the operating system, exit it with either the Stop-A or halt 
commands, and then use some OpenBoot commands, the commands might not 
work as expected. 

For example, suppose you boot the operating system, exit it with Stop-A, then 
execute the probe-scsi command (described in Chapter 2, "Booting and 
Testing Your System"). You may find that probe-scsi fails, and you may not 
be able to resume the operating system. When this happens, type the following 
commands: 



ok sync 
ok boot 



To re-execute an OpenBoot command which fails because the operating system 
has halted, reset the system first, then invoke the command, as shown: 



ok reset 

ok probe-scsi 

ok 



Overview 
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Booting and Testing Your System 2 = 



This chapter describes the most common tasks that you perform using the 
OpenBoot firmware. These tasks let you: 

• Boot your system. 

• Run diagnostics. 

• Display system information. 

• Reset the system. 

Booting Your System 

The most important function of the OpenBoot firmware is to boot the system. 
Booting is the process of loading and executing a standalone program such as 
the operating system. Once it is powered on, the system usually boots 
automatically without user intervention. If necessary you can explicitly initiate 
the boot process from the OpenBoot command interpreter. Automatic booting 
uses the default boot device specified in non- volatile RAM (NVRAM); user- 
initiated booting uses either the default boot device or one specified by the 
user. 

If you want to boot the system from the default boot device, type the following 
command at the Forth Monitor prompt: 



ok boot 
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If you are at the Restricted Monitor prompt, and you want to boot your system, 
type: 



> b 



The boot command has the following format: 

boot [device-specifier] [filename] [options] 
The optional parameters for the boot command are described in Table 2-1. 



Table 2-1 Common Options for the boot Command 



Parameter 


Description 


[device-specifier] 


The name (full path name or alias) of the boot device. Typical values include: 

cdrom (CD-ROM drive) 

disk (hard disk) 

floppy (3-1/2" diskette drive) 

net (Ethernet) 

tape (SCSI tape) 


[filename] 


The name of the program to be booted (for example, stand/diag). filename is relative to the root of 
the selected device and partition (if specified). If filename is not specified, the boot program uses the 
value of the boot-file NVRAM parameter (see Chapter 3). 


[options] 


-a - Prompt interactively for the device and name of the boot file, 
-h - Halt after loading the program. 

(These options are specific to the operating system, and may differ from system to system.) 




Note - Many commands (such as boot and test) that require a device name, 
accept either a full device path name or a device alias. In this manual, the term 
device-specifier is used to indicate that either a device path name or a device 
alias is acceptable for such commands. 




To explicitly boot from the internal disk (for diskfull systems), type: 



ok boot disk 
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To explicitly boot from Ethernet, type: 



ok boot net 



To specify a boot device at the Restricted Monitor prompt, use the b command 
with the name of the boot device as shown in the examples below. 



> b disk (to explicitly boot from the internal disk for diskfull systems) 

> b net (to explicitly boot from Ethernet) 



Device alias definitions vary from system to system. Use the devalias 
command, described in Chapter 1, "Overview," for definitions of your system's 
aliases. Table 2-2 is an example of device aliases and their definitions based on 
SPARCstation 2 and SPARCstation IPX systems. The heading "Old Path" refers 
to the OpenBoot Version 1.x usage for the equivalent SBus device. 



Table 2-2 Typical Device Aliases 



Alias 


Boot Path 


Old Path 


Description 


disk 


/sbus/esp/sd@3,0 


sd(0, 0, 0) 


Default disk (1st internal). 


diskO 


/sbus/esp/sd@3, 0 


sd (0, 0, 0) 


First internal disk sdO. 


diskl 


/sbus/esp/sd@l,0 


sd(0, 1, 0) 


Second internal disk sdl. 


disk2 


/sbus/esp/sd@2, 0 


sd(0,2,0) 


External disk sd2. 


disk3 


/ sbus/esp/sd@0, 0 


sd(0,3, 0) 


External disk sd3. 


tape 


/sbus/esp/st@4, 0 


st (0, 0, 0) 


First tape drive stO. 


tapeO 


/sbus/esp/st@4,0 


st (0, 0, 0) 


First tape drive stO. 


tapel 


/sbus/esp/st@5,0 


st (0, 1, 0) 


Second tape drive stl. 


cdrom 


/sbus/esp/sd@6, 0:c 


sd(0, 6, 2) 


CD-ROM partition c. 


cdroma 


/sbus/esp/ sd@ 6, 0 : a 


sd(0, 6, 0) 


CD-ROM partition a. 


net 


/sbus/le 


le (0, 0, 0) 


Ethernet. 


floppy 


/fd 


fd(0, 0, 0) 


Floppy drive. 
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Note that in Table 2-2 the names sdO, sdl, and so on, are terms used in the 
Solaris® 1.x operating environment to describe these devices. The Solaris 2.x 
operating environment names are different, as shown in Table 2-3 below. 



Table 2-3 Alias Names in the Solaris Operating Environment 



Alias 


Solaris 1.x Name 


Solaris 2.x Name 


disk and diskO 


sdO 


c0t3d0s0 


diskl 


sdl 


cOtldOsO 


disk2 


sd2 


c0t2d0s0 


disk3 


sd3 


cOtOdOsO 



Running Diagnostics 

Several diagnostic routines are available from the Forth Monitor. These on- 
board tests let you check devices such as the network controller, the floppy 
disk system, memory, installed SBus cards and SCSI devices, and the system 
clock. User-installed devices can be tested if their firmware includes a self -test 
feature. 

Table 2-4 lists diagnostic test commands. Remember: device-specifier refers to 
either a device path name or a device alias. 



Table 2-4 Diagnostic Test Commands 



Command 


Description 


probe-scsi 


Identify devices attached to the built-in SCSI bus. 


probe-scsi-all [device-path] 


Perform probe-scsi on all SCSI buses installed in the system below the specified 
device tree node. (If device-path is absent, the root node is used.) 


test device-specifier 


Execute the specified device's self-test method. For example: 
test floppy - test the floppy drive, if installed 

test /memory - test number of megabytes specified in the self test-#megs 

NVRAM parameter; or test all of memory if diag-switch? is true 
test net - test the network connection 


test-all [device-specifier] 


Test all devices (that have a built-in self-test method) below the specified device 
tree node. (If device-specifier is absent, the root node is used.) 


watch-clock 


Test the clock function. 


watch-net 


Monitor the network connection. 
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Testing the SCSI Bus 

To check the built-in SCSI bus for connected devices, type: 



ok probe- 


-scsi 
























Target 1 


























Unit 0 


Disk 


SEAGATE 


ST14! 


30 


SUN04246266 


Copyright 


(C) 


1991 


Seagate 


All 


rights 


reserved 


Target 3 


























Unit 0 


Disk 


SEAGATE 


ST14! 


30 


SUN04245826 


Copyright 


(C) 


1991 


Seagate 


All 


rights 


reserved 


ok 



























To test all the SCSI buses installed in the system, type: 



ok probe-scsi-all 

/iommuSf , e0000000/sbus@f , e0001000/esp@ 3, 2 00000 
Target 6 

Unit 0 Disk Removable Read Only device SONY CD-ROM CDU-8012 3. Id 

/iommu@f , e0 000000/sbus@f , e0 001000/espdma@f , 4 000 00/esp@f , 8 00 00 0 
Target 1 

Unit 0 Disk SEAGATE ST1480 SUN04246266 Copyright (C) 1991 Seagate All rights 
Target 3 

Unit 0 Disk SEAGATE ST1480 SUN04245826 Copyright (C) 1991 Seagate All rights 
ok 



The actual response depends on the devices on the SCSI bus. 

Testing Installed Devices 

To test a single installed device, type: 



ok test device-specifier 



This executes the device method (named self test) of the specified device 
node. Response depends on the self-test of the device node. 
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To test a group of installed devices, type: 



ok test-all 



All devices below the root node of the device tree are tested. The response 
depends on the devices that have a self-test method. If you use the 
device-specifier option with the test-all command, all devices below the 
specified device tree node are tested. 

Testing the Diskette Drive 

The diskette drive test determines whether or not the diskette drive is 
functioning properly. A formatted, high-density (HD) disk must be in the 
diskette drive for this test to be successful. 

To test the diskette drive, type: 



ok test floppy 

Testing floppy disk system. A formatted 
disk should be in the drive. 
Test succeeded, 
ok 



If the test fails, you see an error message. 

To eject the diskette from the diskette drive, type: 



ok eject-floppy 

ok 



If this command fails, you can physically eject the diskette by inserting a 
straightened paper clip into the little hole near the diskette slot. 
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Testing Memory 



When you use the memory testing routine, the system tests the number of 
megabytes of memory specified in the NVRAM parameter self test-#megs. 
(See Chapter 3, "Setting Configuration Parameters," for information on 
NVRAM parameters.) One megabyte of memory is tested as the default. If 
either the hardware diagnostic switch (if the system has one) or the NVRAM 
parameter diag- switch? is enabled, all the memory is tested. 

To test memory, type: 



ok test /memory 

Testing 16 megs of memory at addr 4000000 11 
ok 



In the preceding example, the first number (4000000) is the base address of the 
testing, and the following number (11) is the number of megabytes to go. 

There will be a delay while the PROM tests the system. If the system fails this 
test, you see an error message. 

Testing the Ethernet Controller 

To test the on-board Ethernet controller, type: 



ok test net 




Internal Loopback test - 


( result ) 


External Loopback test - 


( result ) 


ok 





The system responds with a message indicating the result of the test. 



Note - The external loopback portion of this test will fail unless the system is 
connected to Ethernet. 
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Testing the Clock 

To test the clock function, type: 



ok watch-clock 

Watching the 'seconds' register of the real time clock chip. 
It should be ticking once a second. 
Type any key to stop. 

1 

ok 



The system responds by incrementing a number once a second. Press any key 
to stop the test. 

Monitoring the Network 

To monitor the network connection, type: 



ok watch-net 

Internal Loopback test - succeeded 
External Loopback test - succeeded 
Looking for Ethernet packets. 
'.' is a good packet. 'X' is a bad packet. 
Type any key to stop 

X X 

ok 



The system monitors network traffic, displaying " . "each time it receives an 
error-free packet and "X" each time it receives a packet with an error that can 
be detected by the network hardware interface. 



Note - Not all OpenBoot 2.x systems include this test word. 
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Displaying System Information 

The Forth Monitor provides several commands to display system information. 
These commands, listed in Table 2-5, let you display the system banner, the 
Ethernet address for the Ethernet controller, the contents of the ID PROM, and 
the version number of the OpenBoot firmware. (The ID PROM contains 
information specific to each individual machine, including the serial number, 
date of manufacture, and Ethernet address assigned to the machine.) 



Table 2-5 System Information Display Commands 



Command 


Description 


banner 


Display power-on banner. 


show-sbus 


Display list of installed and probed SBus devices. 


. enet-addr 


Display current Ethernet address. 


. idprom 


Display ID PROM contents, formatted. 


.traps 


Display a list of SPARC trap types. 


. version 


Display version and date of the boot PROM. 



Also see the device tree browsing commands in Table 1-4 on page 8. 



Note - If you halt the operating system, type banner, and then resume the 
system, you may find that your color tables have been altered. To restore these 
tables on pre-Solaris 2.0 operating environments, type clear_colormap, then 
select Refresh from the Utilities menu. To restore these tables on Solaris 
2.0 or 2.1 operating environments, select Color Chooser from the 
Properties. . . menu. 
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Resetting the System 



Occasionally, you may need to reset your system. The reset command resets 
the entire system and is similar to performing a power cycle. 

To reset the system, type: 



ok reset 



If your system is set up to run the power-on self-test (POST) and initialization 
procedures on reset, these procedures begin executing once you initiate this 
command. (On some systems, POST is only executed after power-on.) Once 
POST completes, the system either boots automatically or enters the Forth 
Monitor, just as it would have done after a power cycle. 



Note - If you were browsing the device tree, you may need to use the 
device-end command (see Chapter 1, "Overview") before you reset the 
system. 
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Setting Configuration Parameters 3 = 



This chapter describes how to access and modify non-volatile RAM (NVRAM) 
configuration parameters. 

System configuration parameters are stored in the system NVRAM. These 
parameters determine the start-up machine configuration and related 
communication characteristics. You can modify the default values of the 
configuration parameters, and any changes you make remain in effect even 
after a power cycle. Configuration parameters should always be adjusted 
cautiously. When correctly used, these parameters give you flexibility in 
working with your system's hardware. 

The procedures described in this chapter assume that the ok prompt is 
displayed on your screen. See Chapter 1, "Overview," for information about 
entering the Forth Monitor. 
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Table 3-1 lists current NVRAM configuration parameters. 
Table 3-1 NVRAM Configuration Parameters 



Parameter 


Typical Default 


Description 


auto-boot ? 


true 


If true, boot automatically after power on or reset. 


boot-device 


disk 


Device from which to boot. 


boot-file 


empty string 


File to boot (an empty string lets secondary booter choose default). 


boot-f rom 


vmunix 


Boot device and file (1.x only). 


boot-f rom-diag 


le()vmunix 


Diagnostic boot device and file (1.x only). 


diag-device 


net 


Diagnostic boot source device. 


diag-f ile 


empty string 


File from which to boot in diagnostic mode. 


diag-switch? 


false 


If true, run in diagnostic mode. 


f code -debug? 


false 


If true, include name fields for plug-in device FCodes. 


hardware-revision 


no default 


System version information. 


input -device 


keyboard 


Power-on input device (usually keyboard, ttya, or ttyb). 


keyboard- click? 


false 


If true, enable keyboard click. 


keymap 


no default 


Keymap for custom keyboard. 


last -hardware- 
update 


no default 


System update information. 


local-mac-address? 


false 


If true, network drivers use their own MAC address, not system's. 


mf g-switch? 


false 


If true, repeat system self -tests until interrupted with St op -A. 


nvramrc 


empty 


Contents of NVRAMRC . 


oem-banner 


empty string 


Custom OEM banner (enabled by oem-banner? true). 


oem-banner ? 


false 


If true, use custom OEM banner. 


oem-logo 


no default 


Byte array custom OEM logo (enabled by oem-logo? true). 
Displayed in hexadecimal. 


oem-logo? 


false 


If true, use custom OEM logo (else, use Sun logo). 


out put -de vice 


screen 


Power-on output device (usually screen, ttya, or ttyb). 


sbus -probe-list 


0123 


Which SBus slots are probed and in what order. 


screen- # columns 


80 


Number of on-screen columns (characters /line). 


screen— # rows 


34 


Number of on-screen rows (lines). 


scsi-initiator-id 


7 


SCSI bus address of host adapter, range 0-7. 


sd-targets 


31204567 


Map SCSI disk units (1.x only). 


security-#badlogins 


no default 


Number of incorrect security password attempts. 
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Table 3-1 NVRAM Configuration Parameters (Continued) 



Parameter 


Typical Default 


Description 


security— mode 


none 


Firmware security level (options: none, command, or full). 


security— password 


no default 


Firmware security password (never displayed). Do not set this directly. 


self test-#megs 


1 


Megabytes of RAM to test. Ignored if diag-switch? is true. 


skip-vme-loopback ? 


false 


If true, POST does not do VMEbus loopback tests. 


st-targets 


45670123 


Map SCSI tape units (1.x only). 


sunmon-compat ? 


false 


If true, display Restricted Monitor prompt (>). 


testarea 


0 


One-byte scratch field, available for read/write test. 


tpe-link-test ? 


true 


Enable lObaseT link test for built-in twisted pair Ethernet. 


ttya-mode 


9600,8,n,l,- 


TTYA (baud rate, #bits, parity, #stop, handshake). 


ttyb-mode 


9600,8,11,1,- 


TTYB (baud rate, #bits, parity, #stop, handshake). 


ttya-ignore-cd 


true 


If true, operating system ignores carrier-detect on TTYA. 


ttyb-ignore-cd 


true 


If true, operating system ignores carrier-detect on TTYB. 


ttya-rts-dtr-of f 


false 


If true, operating system does not assert DTR and RTS on TTYA. 


ttyb-rts-dtr-of f 


false 


If true, operating system does not assert DTR and RTS on TTYB. 


use-nvramrc? 


false 


If true, execute commands in NVRAMRC during system start-up. 


version2 ? 


true 


If true, hybrid (l.x/2.x) PROM comes up in version 2.x. 


wat chdog- reboot ? 


false 


If true, reboot after watchdog reset. 



Note - Not all OpenBoot systems support all parameters. Defaults may vary 
depending on the type of system and the PROM revision. 
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Displaying and Changing Parameter Settings 



NVRAM configuration parameters can be viewed and changed using the 
commands listed in Table 3-2. 

Table 3-2 Viewing/ Changing Configuration Parameters 



Command 


Description 


printenv 


Display all current parameters and current default values. 
(Numbers are usually shown as decimal values.) 

printenv parameter shows the current value of the named parameter. 


setenv parameter value 


Set parameter to the given decimal or text value. 

(Changes are permanent, but usually only take effect after a reset.) 


set-default parameter 


Reset the value of the named parameter to the factory default. 


set-defaults 


Reset parameter values to the factory defaults. 


The following pages show how these commands can be used. 
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To display a list of the current parameter settings on your system, type: 



ok printenv 










Paramstcr Name 


Value 






Default Value 


OGITl - 1 OgO 


2c 31 


2c 


2d 00 00 00 00 




oem— logo ? 


false 






false 


oern— banner 










oern— banner ? 


false 






false 


output — de vi ce 


ttya 






s creen 


input — devi ce 


ttya 






keyboard 


sbu s — probe - list 


03 






0123 


keyboard - click? 










keymap 










1 1 y b - r t s - dt r - o f f 


false 






false 


1 1 yb — ignore— cd 


true 






true 


ttya-rts-dtr-off 


false 






false 


ttya-ignore-cd 


true 






true 


ttyb-mode 


9600, i 


, n 


1, - 


9600, 8, n, 1, - 


ttya-mode 


9600, i 




1, - 


9600, 8, n, 1, - 


diag-f ile 










diag-device 


net 






net 


boot-file 










boot-device 


disk 






disk 


auto-boot ? 


false 






true 


watchdog- reboot ? 


false 






false 


f code-debug? 


true 






false 


local-mac-address ? 


false 






false 


use-nvramrc? 


false 






false 


nvramrc 










screen- # columns 


80 






80 


screen-trows 


34 






34 


sunmon-compat ? 


false 






true 


security-mode 


none 






none 


security-password 










security- #badlogins 


0 








scsi-initiator-id 


7 






7 


version2 ? 


true 






true 


hardware-revision 










last -hardware-update 










testarea 


0 






0 


mf g-swit ch? 


false 






false 


diag-switch? 


true 






false 


ok 











In the displayed, formatted list of the current settings, numeric parameters are 
shown in decimal, except where noted otherwise. 
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To change a parameter setting, type: 



setenv parameter value 



parameter is the name of the parameter, value is a numeric value or text string 
appropriate to the named parameter. A numeric value is typed as a decimal 
number, unless preceded by Ox, which is the qualifier for a hexadecimal 
number. Most parameter changes do not take effect until the next power cycle or 
system reset. 

For example, to change the setting of the auto-boot? parameter from true to 
false, type: 



ok setenv auto-boot? false 

ok 



You can reset one or most of the parameters to the original defaults using the 

set-default parameter and set-defaults commands. 

For example, to reset the auto-boot? parameter to its original default setting 
(true), type: 



ok set-default auto-boot? 

ok 



To reset most parameters to their default settings, type: 



ok set-defaults 

ok 
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Setting Security Parameters 



The NVRAM system security parameters are: 

• security-mode 

• security-password 

• security-#badlogins 

security-mode can restrict the set of actions that unauthorized users are 
allowed to perform from the Forth Monitor. The three security modes, listed in 
order of least to most secure, are: 

• none 

• command 

• full 

The Restricted Monitor is used to implement the command and full modes. 
When security is set to command or full mode, the OpenBoot firmware will 
come up in the Restricted Monitor. In none security mode, it will come up in 
either the Forth Monitor or the Restricted Monitor, depending on which one is 
the default. 

In none security mode, any command can be typed in the Restricted Monitor, 
and no password is required. In command and full security modes, 
passwords are required to execute certain commands. For example, a password 
is required to get to the Forth Monitor. Once you enter the Forth Monitor, 
however, a password is never required. 

As with many NVRAM parameters, security-mode can be changed with the 
operating system eeprom utility. 
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Command Security 

With security-mode set to command, the system comes up in the Restricted 
Monitor. In this monitor mode, 

• A password is not required if you type the b command. However, if you use 
the b command with a parameter, a password is required. 

• The c command never asks for a password. 

• A password is required to execute the n command. 
Examples are shown in the following screen. 



> b 


(no password required) 


> c 


(no password required) 


> b filename 


(password required) 


PROM Password: 


(password is not echoed as it is typed) 


> n 


(password required) 


PROM Password: 


(password is not echoed as it is typed) 



To set the security password and command security mode, type the following 
at the ok prompt: 



ok password 

ok New password (only first 8 chars are used) : 

ok Retype new password: 

ok setenv security-mode command 

ok 



Note - Although this example works, you should normally set the two security 
parameters with the eeprom command from the operating system. 



The security password you assign follows the same rules as the root 
password: a combination of six to eight letters and numbers. The security 
password can be the same as the root password, or different from it. You do 
not have to reset the system; the security feature takes effect as soon as you 
type the command. 
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A Caution - It is important to remember your security password. If you forget 
this password, you cannot use your system; you will have to call Sun's 
customer support service to make your machine bootable again. 



If you enter an incorrect security password, there will be a delay of about 10 
seconds before the next boot prompt appears. The number of times that an 
incorrect security password is typed is stored in the security-#badlogins 
parameter. This parameter is a 32-bit signed number (680 years worth of 
attempts at 10 seconds per attempt). 

Full Security 

The full security mode is the most restrictive. With security-mode set to 
full, the system comes up in the Restricted Monitor. In this mode: 

• A password is required any time you type the b command. 

• The c command never asks for a password. 

• A password is required to execute the n command. 

Examples are shown below. 



> c 


(no password required) 


> b 


(password required) 


PROM Password: 


(password is not echoed as it is typed) 


> b filename 


(password required) 


PROM Password: 


(password is not echoed as it is typed) 


> n 


(password required) 


PROM Password: 


(password is not echoed as it is typed) 



To set the security password and full security, type the following at the ok 
prompt: 



ok password 

ok New password (only first 8 chars are used) : 

ok Retype new password: 

ok setenv security-mode full 

ok 



Setting Configuration Parameters 



31 



Changing the Power-on Banner 

The banner configuration parameters are: 

• oem-banner 

• oem-banner? 

• oem-logo 

• oem-logo? 

To view the power-on banner, type: 



ok banner 



The PROM displays the system banner. The following example shows a 
SPARCstation 2 banner. The banner for your SPARC system may be different. 



SPARCstation 2, Type 4 Keyboard 

ROM Rev. 2.0, 16MB memory installed, Serial # 289 
Ethernet address 8 : 0 : 20 : d: e2 : 7b, Host ID: 55000121 



The banner consists of two parts: the text field and the logo (over serial ports, 
only the text field is displayed). You can replace the existing text field with a 
custom text message using the oem-banner and oem-banner? configuration 
parameters. 

To insert a custom text field in the power-on banner, type: 



ok setenv oem-banner Hello Mom and Dad 
ok setenv oem-banner? true 
ok banner 

ok 



The system displays the banner with your new message, as shown in the 
following screen. 
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However, the graphic logo must be handled somewhat differently, oem-logo 
is a 512-byte array, containing a total of 4096 bits arranged in a 64 x 64 array. 
Each bit controls one pixel. The most significant bit (MSB) of the first byte 
controls the upper-left corner pixel. The next bit controls the pixel to the right 
of it, and so on. 

To create a new logo, first create a Forth array containing the correct data; then 
copy this array into oem-logo. In the following example, the array is created 
using Forth commands. (It could also be done under the operating system 
using the eeprom command.) The array is then copied using the to command. 
The example below fills the top half of oem-logo with an ascending pattern. 



ok 


create logoarray d# 512 


allot 


ok 


logoarray d# 256 0 do i 


over i + c ! loop drop 


ok 


logoarray d# 256 to oem- 


-logo 


ok 


setenv oem-logo? true 




ok 


banner 





To restore the original Sun power-on banner, set the oem-logo? and 

oem-banner? parameters to false. 



ok setenv oem-logo? false 
ok setenv oem-banner? false 

ok 



Because the oem-logo array is so large, printenv displays approximately the 
first 8 bytes (in hexadecimal). Use the oem-logo dump command to display the 
entire array. The oem-logo array is not erased by set-defaults, since it 
might be difficult to restore the data. However, oem-logo? is set to false when 
set-defaults executes, so the custom logo is no longer displayed. 
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Input and Output Control 

The configuration parameters related to the control of system input and output 
are: 

• input-device 

• output-device 

• screen-#columns 

• screen-#rows 

• ttya-mode 

• ttyb-mode 

You can use these parameters to assign the power-on defaults for input and 
output and to adjust the communication characteristics of the TTYA and TTYB 
serial ports. Except for the ttya-mode and ttyb-mode results, these values 
do not take effect until the next power cycle or system reset. 

Selecting Input and Output Device Options 

The input-device and output-device parameters control the system's 
selection of input and output devices after a power-on reset. The default 
input-device value is keyboard and the default output-device value is 
screen. Input and output can be set to the values in Table 3-3. 



Table 3-3 I/O Device Parameters 



Options 


Description 


device-specifier 


Device identified by that device path name or alias. 


keyboard 


(Input only) Default system keyboard. 


screen 


(Output only) Default graphics display. 


ttya 


Serial port A. 


ttyb 


Serial port B. 



When the system is reset, the named device becomes the default input or 
output device. (If you want to temporarily change the input or output device, 
use the input or output commands described in Chapter 4, "Using Forth 
Tools.") 
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To set TTYA as the power-on default input device, type: 



ok setenv input-device ttya 

ok 



If you select keyboard for input-device, and the device is not plugged in, 
input is accepted from ttya after the next power cycle or system reset. If you 
select screen for output-device, but no frame buffer is available, output is 
sent to ttya after the next power cycle or system reset. 

To specify an SBus "bwtwo" frame buffer as the default output device 
(especially if there are multiple frame buffers in the system), type: 



ok setenv output-device /sbus/bwtwo 

ok 



Setting Serial Port Characteristics 

The default settings for both TTYA and TTYB for most Sun systems are: 

9600 baud, 8 data bits, no parity, 1 stop bit, no handshake 

The communications characteristics for the two serial ports, TTYA and TTYB, 
are set using the following values for the ttya-mode and ttyb-mode 
parameters: 

• baud = 110, 300, 1200, 2400, 4800, 9600, 19200, or 38400 bits/second 

• #bits = 5, 6, 7, or 8 (data bits) 

• parity = n (none), e (even), or o (odd), parity bit 

• #stop = 1 (1), . (1.5), or 2 (2) stop bits 

• handshake = - (none), h (hardware (rts/cts)), or s (software (xon/xoff)). 
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For example, to set TTYA to 1200 baud, seven data bits, even parity, one stop 
bit, and no handshake, type: 



ok setenv ttya-mode 1200, 7, e,l,- 

ok 



Changes to these parameter values take effect immediately. 



Note - rts/cts and xon/xoff handshaking are not implemented on some 
systems. When a selected protocol is not implemented, the handshake 
parameter is accepted but ignored; no messages are displayed. 



Selecting Boot Options 

You can use the following configuration parameters to determine whether or 
not the system will boot automatically after a power cycle or system reset. 

• auto-boot? 

• boot-device 

• boot-file 

If auto-boot? is true, then the system boots automatically (using the 

boot-device and boot-file values). 

These parameters can also be used during manual booting to select the boot 
device and the program to be booted. For example, to specify auto-booting 
from the Ethernet server, type: 



ok setenv boot-device net 
ok boot 



Specified booting usually begins immediately. 



Note - boot-device and boot-file are specified differently with 
diag-switch? set to true. See the next section for more information. 
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Controlling Power-on Self-test 



The power-on testing parameters are: 

• diag-device 

• diag-file 

• diag-switch? 

• mfg-switch? 

• selftest-#megs 

Most systems have a factory default of false for the diag-switch? 
parameter. To set diag-switch? to true, type: 



ok setenv diag-switch? true 

ok 



Enabling diag-switch? causes the system to perform more thorough 
self-tests during any subsequent power-on process. Once diag-switch? is 
enabled, additional status messages are sent out (some to TTYA and some to 
the specified output device), all of memory is tested, and different default boot 
options are used. The boot PROM tries to boot the program specified by the 
diag-file parameter, from the device specified by diag-device. 



Note - Some SPARC systems have a hardware diagnostic switch. The system 
runs the full tests on power-on if either the hardware switch or 

diag-switch? is set. 



You can also force diag-switch? to true by using the Stop-D key sequence 
during power-on. 

To set diag-switch? to false, type: 



ok setenv diag-switch? false 

ok 



When diag-switch? is false, the system does not call out the diagnostic 
tests as they are run (unless a test fails) and runs a reduced set of diagnostics. 
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A portion of NVRAM, whose size depends on the particular SPARC system, is 
called NVRAMRC. It is reserved to store user-defined commands that are 
executed during start-up. 

Typically, NVRAMRC would be used by a device driver to save start-up 
configuration parameters, to patch device driver code, or to define installation- 
specific device configuration and device aliases. It also could be used for bug 
patches or for user-installed extensions. Commands are stored in ASCII, just as 
the user would type them at the console. 

There are two NVRAMRC-related configuration parameters: 

• nvramrc 

• use-nvramrc? 

Commands in NVRAMRC are executed during system start-up if 
use-nvramrc? is set to true. Almost all Forth Monitor commands can be 
used here. The following are exceptions: 

• banner (use with caution) 

• boot 

• go 

• nvedit 

• password 

• reset 

• setenv security-mode 
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Editing the Contents ofNVRAMRC 

The NVRAMRC editor, nvedit, lets you create and modify the contents of 
NVRAMRC using the commands listed in Table 3-4. 



Table 3-4 NVRAMRC Editor Commands 



Command 


Description 


nvalias alias device-path 


Store the command "devalias alias device-path" in NVRAMRC. The alias persists until 
the nvunalias or set-defaults commands are executed. 


nvedit 


Enter the NVRAMRC editor. If data remains in the temporary buffer from a previous 
nvedit session, resume editing those previous contents. If not, read the contents of 
NVRAMRC into the temporary buffer and begin editing it. 


nvquit 


Discard the contents of the temporary buffer, without writing it to NVRAMRC. Prompt 
for confirmation. 


nvrecover 


Recover the contents of NVRAMRC if they have been lost as a result of the execution of 
set-defaults; then enter the editor as with nvedit. nvrecover fails if nvedit is 
executed between the time that the NVRAMRC contents were lost and the time that 

nvrecover is executed. 


nvrun 


Execute the contents of the temporary buffer. 


nvstore 


Copy the contents of the temporary buffer to NVRAMRC; discard the contents of the 
temporary buffer. 


nvunalias alias 


Delete the corresponding alias from NVRAMRC. 



Note - Not all OpenBoot 2.x systems include the nvalias and nvunalias 
commands. 
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The editing commands shown in Table 3-5 are used within the NVRAM editor. 

Table 3-5 nvedit Keystroke Commands 



Keystroke 


Description 


Control-B 


Move backward one character. 


Control-C 


Exit the editor and return to the OpenBoot command interpreter. The temporary buffer is 
preserved but is not written back to NVRAMRC. (Use nvstore afterwards to write back the 
temporary buffer.) 


Control-F 


Move forward one character. 


Control-K 


If at the end of a line, join the next line to the current line (that is, delete the new line). 


Control-L 


List all lines. 


Control-N 


Move to the next line of the NVRAMRC editing buffer. 


Control-0 


Insert a new line at the cursor position and stay on the current line. 


Control-P 


Move to the previous line of the NVRAMRC editing buffer. 


Delete 


Delete the previous character. 


Return 


Insert a new line at the cursor position and advance to the next line. 



Other standard line editor commands are described in Chapter 4, "Using Forth 
Tools." 

Activating an NVRAMRC File 

Use the following steps to activate an NVRAMRC command file: 

1. At the ok prompt, type nvedit 

Edit the contents of NVRAMRC using editor commands. 

2. Type Control-C to get out of the editor and back to the ok prompt. 

3. Type nvstore to save your changes. 

4. Enable the interpretation of NVRAMRC by typing: 
setenv use-nvramrc? true 

5. Type reset to reset the system and execute the NVRAM contents, or type 
nvramrc eval to execute the contents directly. If you have not yet typed 
nvstore to save your changes, type nvrun to execute the contents of the 
temporary edit buffer. 
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The following example shows you how to create a simple colon definition in 
NVRAMRC. 



ok nvedit 

0: : hello ( — ) 

1: ." Hello, world. " cr 

2: ; 

3: A -C 

ok nvstore 

ok setenv use-nvramrc? true 
ok reset 

ok hello 

Hello, world, 
ok 



Notice the nvedit line number prompts (0:, 1:, 2:, 3:) in the above example. 
These prompts may be different on some systems. 
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Using Forth Tools 



This chapter introduces Forth as it is implemented in the OpenBoot firmware. 
Even if you are familiar with the Forth programming language, work through 
the examples shown in this chapter; they provide specific, OpenBoot-related 
information. 

The version of Forth contained in the OpenBoot firmware is based on Forth-83, 
with extensions. Appendix E, "Forth Word Reference," lists the complete set of 
available commands. Words that are specifically used for writing FCode 
programs for SBus devices are described in the manual Writing FCode Programs 
(part number 801-7050-10). 



Note - This chapter assumes that you know how to enter and leave the Forth 
Monitor. At the ok prompt, if you type commands that hang the system and 
you cannot recover using St op -A, you may need to perform a power cycle to 
return the system to normal operation. 
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Forth has a very simple command structure. Forth commands, also called 
Forth words, consist of any combination of characters that can be printed — for 
example, letters, digits, or punctuation marks. Examples of legitimate words 
are shown below: 

8 

dump 

0< 
+ 

probe-scsi 

To be recognized as commands, Forth words must be separated by one or more 
spaces (blanks). Pressing Return at the end of any command line executes the 
typed commands. (In all the examples shown, a Return at the end of the line is 
assumed.) 

A command line can have more than one word. Multiple words on a line are 
executed one at a time, from left to right, in the order in which they were 
typed. For example: 



ok testa testb teste 

ok 



is equivalent to: 



ok testa 
ok testb 
ok teste 

ok 



In the OpenBoot implementation of Forth, uppercase and lowercase letters are 
equivalent. Therefore, testa, TESTA, and TesTa all invoke the same 
command. 
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Some commands generate large amounts of output (for example, dump or 
words). You can interrupt such a command by pressing any key except Q. (If 
you press Q, the output is aborted, not suspended.) Once a command is 
interrupted, output is suspended and the following message appears: 



More [<space>, <cr>, q] ? 



Press the space bar (<space>) to continue, press Return (<cr>) to output one 
more line and pause again, or type q to abort the command. When you are 
generating more than one page of output, the system automatically displays 
this prompt at the end of each page. 

Using Numbers 

Enter a number by typing its value, for example, 55 or -123. Forth accepts only 
integers (whole numbers); fractional values (for example, 2/3) are not allowed. 
A decimal point in a number is ignored, so 5.77 is understood as 577. Use one 
or more spaces to separate a number from a word or from another number. 

The OpenBoot firmware performs 32-bit integer arithmetic, and all numbers 
are 32-bit values unless otherwise specified. Because hexadecimal (base 16) 
numbers are so commonly used, the Forth Monitor automatically interprets all 
numbers in hexadecimal, not decimal (base 10). Therefore, adding 8 and 7 
returns the value f , not 1 5 . You can change the operating number base. 

The commands decimal and hex cause all subsequent numeric input and 
output to be performed in base 10 or base 16, respectively. To operate in 
decimal, type: 



ok decimal 

ok 



To change to hexadecimal type: 



ok hex 

ok 
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To find out what number base is currently active, use the following example: 



ok 10 .d 

16 
ok 



The 1 6 on the display shows that you are operating in hexadecimal. If 1 0 
showed on the display it would mean that you are in decimal base. 

The Stack 

The Forth stack is a last-in, first-out buffer used for temporarily holding 
numeric information. Think of it as a stack of books: the last one you put on 
the top of the stack is the first one you take off. Understanding the stack is 
essential to using Forth. 

To place a number on the stack, simply type its value. 



ok 44 (The value 44 is now on top of the stack) 

ok 7 (The value 7 is now on top, with 44 just underneath) 

ok 



Displaying Stack Contents 

The contents of the stack are normally invisible. However, properly visualizing 
the current stack contents is important for achieving the desired result. To 
show the stack contents with every ok prompt, type: 



ok showstack 

44 7 ok 8 

47 7 8 ok showstack 

ok 



The topmost stack item is always shown as the last item in the list, 
immediately before the ok prompt. In the above example, the topmost stack 
item is 8. 
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On older systems, showstack, once invoked, remains in effect until a machine 
reset takes place. Starting with release 2.6 of the OpenBoot PROM, you can 
toggle the showstack command on and off. 



Note - In some of the examples in this chapter, showstack is enabled. In those 
examples, each ok prompt is immediately preceded by a display of the current 
contents of the stack. The examples work the same if showstack is not 
enabled, except that the stack contents are not displayed. 



Nearly all words that require numeric parameters fetch those parameters from 
the top of the stack. Any values returned are generally left on top of the stack, 
where they can be viewed or consumed by another command. For example, 
the Forth word + removes two numbers from the stack, adds them together, 
and leaves the result on the stack. In the example below, all arithmetic is in 
hexadecimal. 



44 7 8 ok + 
44 f ok + 

53 ok 



Once the two values are added together, the result is put onto the top of the 
stack. The Forth word " . " removes the top stack item and displays that value 
on the screen. For example: 



53 


ok 12 


53 


12 ok . 


12 




53 


ok . 


53 




ok 


(The stack is now empty) 


ok 


3 5+. 


8 

ok 


(The stack is now empty) 


ok 




Stack Underflow 


ok 
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The Stack Diagram 

To aid programming, there is a stack diagram in the form ( — ) for every defined 
Forth word. The stack diagram specifies what happens to the stack with the 
execution of the word. 

Entries to the left of — show stack items that are consumed (or removed from 
the stack and used by the operation of that word). Entries to the right of — 
show stack items that are left on the stack after the word finishes execution. 
For example, the stack diagram for the word + is: ( nl n2 — n3 ), and the stack 
diagram for the word " . " is: ( n — ). Therefore, + removes two numbers (nl 
and n2), then leaves their sum (n3) on the stack. The word " . " removes the 
number on the top of the stack (n) and displays it. 

Words that have no effect on the contents of the stack (such as showstack or 
decimal) , have a ( -- ) stack diagram. 

Occasionally, a word will require another word or other text immediately 
following it. The word see, used in the form see thisword ( — ), is such an 
example. 

Stack items are generally written using descriptive names to help clarify 
correct usage. See Table 4-1 for stack item abbreviations used in this manual. 



Table 4-1 Stack Item Notation 



Notation 


Description 


1 


Alternate stack results, for example: ( input — adr len false 1 result true ). 


? 


Unknown stack items (changed from ???). 


? ? ? 


Unknown stack items. 


acf 


Code field address. 


adr 


Memory address (generally a virtual address). 


adrl6 


Memory address, must be 16-bit aligned. 


adr32 


Memory address, must be 32-bit aligned. 


adr64 


Memory address, must be 64-bit aligned. 


byte bxxx 


8-bit value (smallest byte in a 32-bit word). 


char 


7-bit value (smallest byte), high bit unspecified. 


cnt 
len 
size 


Count or length. 
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Table 4-1 Stack Item Notation (Continued) 


Notation 


Description 


flag xxx? 


0 = false; any other value = true (usually -1). 


long Lxxx 


32-bit value. 


n nl n2 n3 


Normal signed values (32-bit). 


+n u 


Unsigned, positive values (32-bit). 


n [64] 

(n . low n . hi ) 


Extended-precision (64-bit) numbers (2 stack items). 


phys 


Physical address (actual hardware address). 


pstr 


Packed string (adr len means unpacked string). 


virt 


Virtual address (address used by software). 


word wxxx 


16-bit value (smallest two bytes in a 32-bit word). 



Manipulating the Stack 

Stack manipulation commands (described in Table 4-2) allow you to add, 
delete, and reorder items on the stack. 

Table 4-2 Stack Manipulation Commands 



Command 


Stack Diagram 


Description 


-rot 


( nl n2 n3 - n3 nl n2 ) 


Inversely rotate 3 stack items. 


>r 


(n-) 


Move a stack item to the return stack. (Use with caution.) 


?dup 


( n - n n 1 0 ) 


Duplicate the top stack item if it is non-zero. 


2drop 


( nl n2 - ) 


Remove 2 items from the stack. 


2dup 


( nl n2 - nl n2 nl n2 ) 


Duplicate 2 stack items. 


2over 


( nl n2 n3 n4 - nl n2 n3 n4 nl n2 ) 


Copy second 2 stack items. 


2rot 


( nl n2 n3 n4 n5 n6 - n3 n4 n5 n6 nl n2 ) 


Rotate 3 pairs of stack items. 


2 swap 


( nl n2 n3 n4 - n3 n4 nl n2 ) 


Exchange 2 pairs of stack items. 


3drop 


( nl n2 n3 - ) 


Remove 3 items from the stack. 


3dup 


( nl n2 n3 - nl n2 n3 nl n2 n3 ) 


Duplicate 3 stack items. 


clear 


( ??? — ) 


Empty the stack. 


depth 


( ??? — 7?7 +n ) 


Return the number of items on the stack. 


drop 


(n-) 


Remove top item from the stack. 


dup 


( n — n n ) 


Duplicate the top stack item. 


nip 


( nl n2 - n2 ) 


Discard the second stack item. 
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Table 4-2 Stack Manipulation Commands (Continued) 



Command 


Stack Diagram 


Description 


over 


( nl n2 -- nl n2 nl ) 


Copy second stack item to top of stack. 


pick 


( ??? +n - ??? n2 ) 


Copy +n-th stack item (1 pick = over). 


r> 


(-n) 


Move a return stack item to the stack. (Use with caution.) 


r@ 


(~n) 


Copy the top of the return stack to the stack. 


roll 


( ??? +n - ? ) 


Rotate +n stack items (2 roll = rot). 


rot 


( nl n2 n3 -- n2 n3 nl ) 


Rotate 3 stack items. 


swap 


( nl n2 -- n2 nl ) 


Exchange the top 2 stack items. 


tuck 


( nl n2 -- n2 nl n2 ) 


Copy top stack item below second item. 



A typical use of stack manipulation might be to display the top stack item 
while preserving all stack items, as shown in this example: 



5 77 


ok dup 


(Duplicates the top item on 


the 


stack) 


5 77 


77 ok . 


(Removes and displays the 


top 


stack item) 


77 










5 77 


ok 









Creating Custom Definitions 



Forth provides an easy way to create custom definitions for new command 
words. Table 4-3 shows the Forth words used to create custom definitions. 

Table 4-3 Colon Definition Words 



Command 


Stack Diagram 


Description 


: name 


(--) 


Start creating a new definition. 




(--) 


Finish creating a new definition. 



Definitions for new commands are called colon definitions, named after the 
" : " word used to create them. For example, suppose you want to create a new 
word, add 4, that will add any four numbers together and display the result. 
You would create the definition as follows: 



ok 


add4 + + + . 


f 


ok 
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The ; (semicolon) marks the end of the definition that defines add4 to have the 
behavior (+ + + .)• The three addition operators (+) reduce the four stack items 
to a single sum on the stack; then " . " removes and displays that result. An 
example follows. 



okl233+++ . 

9 

ok 1 2 3 3 add4 

9 

ok 



Definitions are stored in local memory, which means they are forgotten if a 
machine reset takes place. To keep useful definitions, put them into a text file 
(using a text editor under your operating system or using the NVRAMRC 
editor). This text file can then be loaded as needed. (See Chapter 5, "Loading 
and Executing Programs," for more information on loading files.) 

When you type a definition in the Forth Monitor, the ok prompt becomes a ] 
(right square bracket) prompt after you type the : (colon) and before you type 
the ; (semicolon). For example, you could type the definition for add4 like 
this: 



ok : add 4 
] + + + 

] • 

] ; 

ok 



Every definition you create (in a text file) should have a stack effect diagram 
shown with that definition, even if the stack effect is nil ( — ). This is vital 
because the stack diagram shows the proper use of that word. Also, use 
generous stack comments within complex definitions; this helps trace the flow 
of execution. For example, when creating add4, you could define it as: 



: add4 ( nl n2 n3 n4 — ) + + + . ; 
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Or you could define add4 as follows: 



: add4 ( nl n2 n3 n4 — ) 
+ + + ( sum ) 



Note - The ( (open parenthesis) is a Forth word meaning to ignore the 
following text up to ) (the closing parenthesis). Like any other Forth word, the 
open parenthesis must have one or more spaces following it. 



Using Arithmetic Functions 

The commands listed in Table 4-4 perform basic arithmetic with items on the 
data stack. 



Table 4-4 Arithmetic Functions 



Command 


Stack Diagram 


Description 


* 


( nl n2 — n3 ) 


Multiply nl * n2. 


+ 


( nl n2 - n3 ) 


Add nl + n2. 




( nl n2 - n3 ) 


Subtract nl - n2 . 


/ 


( nl n2 — quot ) 


Divide nl / n2; remainder is discarded. 


/mod 


( nl n2 — rem quot ) 


Remainder, quotient of nl / n2. 


<< 


( nl +n - n2 ) 


Left-shift nl by +n bits. 




( nl +n — n2 ) 


Right-shift nl by +n bits. 


>>a 


( nl +n - n2 ) 


Arithmetic right-shift nl by +n bits. 


*/ 


( nl n2 n3 -- n4 ) 


nl * n2 / n3. 


*/mod 


( nl n2 n3 — rem quot ) 


Remainder, quotient ofnl*n2/n3. 


1 + 


( nl - n2 ) 


Add 1. 


1- 


( nl - n2 ) 


Subtract 1. 


2 * 


( nl -- n2 ) 


Multiply by 2. 


2 + 


( nl - n2 ) 


Add 2. 


2- 


( nl - n2 ) 


Subtract 2. 


21 


( nl - n2 ) 


Divide by 2. 
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Table 4-4 Arithmetic Functions (Continued) 



Command 


Stack Diagram 


Description 


abs 


( n — u ) 


Absolute value. 


aligned 


( nl — n2 ) 


Round nl up to the next multiple ot 4. 


and 


( nl n2 -- n3 ) 


Bitwise logical AND. 


bounds 


( startadr len — endadr startadr ) 


Convert startadr len to endadr startadr for do loop. 


bl join 


( b.low b2 b3 b.hi - long ) 


Join four bytes to form a 32-bit longword. 


bw join 


( b.low b.hi — word ) 


Join two bytes to form a 16-bit word. 


flip 


( wordl — word2 ) 


Swap the bytes within a 16-bit word. 


lbsplit 


( long — b.low b2 b3 b.hi ) 


Split a 32-bit longword into four bytes. 


lwsplit 


( long — w.low w.hi ) 


Split a 32-bit longword into two 16-bit words. 


max 


( nl n2 — n3 ) 


n3 is maximum of nl and n2. 


min 


( nl n2 - n3 ) 


n3 is minimum of nl and n2. 


mod 


( nl n2 — rem ) 


Remainder of n 1 / n2. 


negate 


( nl - n2 ) 


Change the sign of n 1 . 


not 


( nl - n2 ) 


Bitwise ones complement. 


or 


( nl n2 - n3 ) 


Bitwise logical OR. 


u*x 


( ul u2 -- product[64] ) 


Multiply 2 unsigned 32-bit numbers; yield unsigned 64-bit 
product. 


u/mod 


( ul u2 — un.rem un.quot ) 


Divide unsigned 32-bit number by an unsigned 32-bit number; 
yield 32-bit remainder and quotient. 


u2/ 


( ul - u2 ) 


Logical right shift 1 bit; zero shifted into vacated sign bit. 


wbsplit 


( word — b.low b.hi ) 


Split 16-bit word into two bytes. 


wf lip 


( longl — long2 ) 


Swap halves of 32-bit longword. 


wl join 


( w.low w.hi — long ) 


Join two words to form a longword. 


x+ 


( nl[64] n2[64] - n3[64] ) 


Add two 64-bit numbers. 


x- 


( nl[64] n2[64] - n3[64] ) 


Subtract two 64-bit numbers. 


xor 


( nl n2 -- n3 ) 


Bitwise exclusive OR. 


xu/mod 


( ul[64] u2 -- rem quot ) 


Divide unsigned 64-bit number by unsigned 32-bit number; 
yield 32-bit remainder and quotient. 
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The Forth Monitor provides interactive commands for examining and setting 
memory. Use the Forth Monitor to: 

• Read and write to any virtual address. 

• Map virtual addresses to physical addresses. 

Memory operators let you read from and write to any memory location. All 
memory addresses shown in the examples that follow are virtual addresses. 

A variety of 8-bit, 16-bit, and 32-bit operations are provided. In general, 
a c (character) prefix indicates an 8-bit (one byte) operation; a w (word) prefix 
indicates a 16-bit (two byte) operation; and an L (longword) prefix indicates a 
32-bit (four byte) operation. 



Note - "L" is sometimes printed in uppercase to avoid confusion with 1 (the 
number one). 



adrl6, adr32, and adr64 indicate addresses with alignment restrictions. For 
example, adr32 indicates 32-bit (4 byte) alignment; so this address must be 
evenly divisible by 4, as shown in the following example: 



ok 4028 L@ 
ok 4029 L@ 

Memory address not aligned 
ok 



The Forth interpreter implemented in the OpenBoot firmware adheres closely 
to the Forth 83-Standard in most respects. One major exception is that the 
OpenBoot Forth implementation uses 32-bit numbers instead of 16-bit 
numbers. In most cases, this difference is not visible to you. For example, @ and 
! (described in this section) work with variables as expected. If you 
explicitly want a 16-bit fetch or a 32-bit fetch, use w@ or L@ instead of @. Other 
commands also follow this convention. 
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Table 4-5 lists the commands used to access memory. 
Table 4-5 Memory Access Commands 



Command 


Stack Diagram 


Description 


i 


( n adrl6 — ) 


Store a 32-bit number at adr 1 6, must be 16-bit aligned. 


+ ! 


( n adrl6 — ) 


Add n to the 32-bit number stored at adrl 6, must be 16-bit aligned. 


<w@ 


( adrl6 — n ) 


Fetch signed 16-bit word at adrl 6, must be 16-bit aligned. 


9 


( adrl6 -- ) 


Display the 32-bit number at adrl 6, must be 16-bit aligned. 


@ 


( adrl6 — n ) 


Fetch a 32-bit number from adr 1 6, must be 16-bit aligned. 


Z ! 


\ ni nz aurio — ) 


Store 2 numbers at adrl 6, n2 at lower address, must be 16-bit 
aligned. 


z is 


( adrl6 — nl n2 ) 


Fetch 2 numbers from adrl6, n2 from lower address, must be 16-bit 
aligned. 


DlanK 


( adr u — ) 


Set u bytes of memory to space (decimal 32). 


C ! 


( n adr — ) 


Store low byte of n at adr. 


c? 


( adr — ) 


Display the byte at adr. 


c@ 


( adr — byte ) 


Fetch a byte from adr. 


cmove 


( adrl adr2 u — ) 


Copy u bytes from adrl to adr2, starting at low byte. 




( adrl adr2 u — ) 


Copy u bytes from adrl to adr2, starting at high byte. 


cpeek 


( adr — false I byte true ) 


Fetch the byte at adr. Return the data and true if the access was 
successful. Return false if a read access error occurred. 


cpoke 


( byte adr — okay? ) 


Store the byte to adr. Return true if the access was successful. 
Return false if a write access error occurred. 


comp 


( adrl adr2 len — n ) 


Compare two byte arrays, n = 0 if arrays are identical, 
n = 1 if first byte that is different is greater in array#l, 
n = -1 otherwise. 


d! 


( nl n2 adr64 -- ) 


Store two 32-bit numbers at adr64, must be 64-bit aligned. 
Order is implementation-dependent. 


d? 


( adr64 - ) 


Display the two 32-bit numbers at adr 6 4, must be 64-bit aligned. 
Order is implementation-dependent. 


d@ 


( adr64- nl n2 ) 


Fetch two 32-bit numbers from adr64, must be 64-bit aligned. 
Order is implementation-dependent. 


dump 


( adr len — ) 


Display len bytes of memory starting at adr. 


erase 


( adr u -- ) 


Set u bytes of memory to 0. 


fill 


( adr size byte — ) 


Set size bytes of memory to byte. 


L! 


( n adr32 - ) 


Store a 32-bit number at adr32, must be 32-bit aligned. 
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Table 4-5 Memory Access Commands (Continued) 



Command 


Stack Diagram 


Description 


L? 


( adr32 - ) 


Display the 32-bit number at adr32, must be 32-bit aligned. 


L@ 


( adr32 — long ) 


Fetch a 32-bit number from adr32, must be 32-bit aligned. 


If lips 


( adr len — ) 


Exchange 16-bit words within 32-bit longwords in specified region. 


lpeek 


( adr32 — false 1 long true ) 


Fetch the 32-bit quantity at adr32. Return the data and true if the 
access was successful. Return false if a read access error occurred. 


lpoke 


( long adr32 — okay? ) 


Store the 32-bit quantity at adr32. Return true if the access was 
successful. Return false if a a write access error occurred. 


move 


( adrl adr2 u — ) 


Copy u bytes from adrl to adr2, handle overlap properly. 


off 


( adrl6 -- ) 


Store false (32-bit 0) at adrl 6. 


on 


( adrl6 -- ) 


Store true (32-bit -1) at adrl 6. 


unaligned-L ! 


( long adr — ) 


Store a 32-bit number, any alignment. 


unaligned-L@ 


( adr — long ) 


Fetch a 32-bit number, any alignment. 


unaligned-w ! 


( word adr — ) 


Store a 16-bit number, any alignment. 


unaligned-w@ 


( adr — word ) 


Fetch a 16-bit number, any alignment. 


w! 


( n adrl6 — ) 


Store a 16-bit number at adr 1 6, must be 16-bit aligned. 


w? 


( adrl6 -- ) 


Display the 16-bit number at adrl 6, must be 16-bit aligned. 


w@ 


( adrl6 -- word ) 


Fetch a 16-bit number from adr 1 6, must be 16-bit aligned. 


wf lips 


( adr len — ) 


Exchange bytes within 16-bit words in specified region. 


wpeek 


( adrl6 — false 1 word true ) 


Fetch the 16-bit quantity at adrl6. Return the data and true if the 
access was successful. Return false if a read access error occurred. 


wpoke 


( word adrl6 — okay? ) 


Store the 16-bit quantity to adrl 6. Return true if the access was 
successful. Return false if a write access error occurred. 
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The dump command is particularly useful. It displays a region of memory as 
both bytes and ASCII values. The example below displays the contents of 20 
bytes of memory starting at virtual address 10000. It also shows you how to 
read from and write to a memory location. 



ok 10000 20 dump (Display 20 bytes of memory starting at virtual address 10000) 

\/ 1234567 89abcdef vl234 5 678 9abcdef 

10000 05 75 6e 74 69 6c 00 40 4e d4 00 00 da 18 00 00 . until . @NT .. Z .. . 

10010 ce da 00 00 f4 f4 00 00 fe dc 00 00 d3 0c 00 00 NZ . . tt . . ~\ . . S . . . 
ok 22 10004 c! (Change 8-bit byte at location 10004 to 22) 
ok 



If you try (with @, for example) to access an invalid memory location, the 
operation immediately aborts and the PROM displays an error message, such 

as Data Access Exception or Bus Error. 

Table 4-6 lists memory mapping commands. 



Table 4-6 Memory Mapping Commands 



Command 


Stack Diagram 


Description 


alloc-mem 


( size — virt ) 


Allocate and map size bytes of available memory; return the virtual 
address. Unmap with free-mem. 


free-mem 


( virt size -- ) 


Free memory allocated by alloc-mem. 


free-virtual 


( virt size -- ) 


Undo mappings created with memmap. 


map? 


( virt -- ) 


Display memory map information for the virtual address. 


memmap 


( phys space size — virt ) 


Map a region of physical addresses; return the allocated virtual 
address. Unmap with free-virtual. 


obio 


( — space ) 


Specify the device address space for mapping. 


obmem 


( — space ) 


Specify the onboard memory address space for mapping. 


sbus 


( — space ) 


Specify the SBus address space for mapping. 



memmap will always work correctly for general mapping of any device, to 
generate a virtual address for accessing the device. 
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A general method for mapping any SBus device directly from the Forth 
monitor (ok prompt) without needing to know system-dependent device 
addresses follows. The method will work on any OpenBoot 2.0 system or later: 



ok 


" /sbus" 


select-dev 






ok 


(offset) 


(slot*) (size) 


map- in 


( virt ) 


ok 











For example, to inspect the FCode PROM for a device in slot #3 of a system, 
use" 



ok " /sbus" select-dev 

ok 0 3 1000 map-in .s 

f fed3000 

ok dup 2 0 dump 

{ dump of first 20 bytes of FCode PROM } 
ok 



Note - On some systems, the pathname for the system SBus may vary, for 
example: 

" /iommu/sbus" (for sun4m machines) 
" /io-unit/sbi" (for sun4d machines) 

show-devs list of all system devices will show the correct pathname. 



Note - Future systems may not work correctly in the most general cases if you 
directly place ( offset size ) on the stack. If you encounter problems 
doing this, try the following, more general approach: 

ok " /sbus" select-dev 

ok " 3,0" decode-unit ( offset space ) 

ok 1000 map-in ( virt ) 

ok 
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The following screen is an example of the use of alloc-mem and free-mem. 

• alloc-mem allocates 4000 bytes of memory, and the starting address 
(f fef 7a48) of the reserved area is displayed. 

• dump displays the contents of 20 bytes of memory starting at ffef7a4 8. 

• This region of memory is then filled with the value 55. 

• Finally free-mem returns the 4000 allocated bytes of memory starting at 

ffef7a48. 



ok 


























ok 4000 


alloc-mem . 
























ffef 7a4S 


3 
























ok 


























ok ffef7a48 constant temp 




















ok temp 


20 dump 


























0 1 2 3 4 5 


6 


7 


\/ 


9 


a 


b 


c 


d 


e 


f 


01234567v9abcdef 


f fef7a40 


00 00 f5 5f 00 00 


40 


08 


ff 


ef 


o4 


40 


ff 


ef 


03 


c8 


. .u_. . @ . . oD@ . o .H 


f fef7a50 


00 00 00 00 00 00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 




f fef7a60 


00 00 00 00 00 00 


00 


00 


00 


00 


00 


00 


00 


00 


00 


00 




ok temp 


20 55 fill 
























ok temp 


20 dump 


























0 1 2 3 4 5 


6 


7 


\/ 


9 


a 


b 


c 


d 


e 


f 


01234567v9abcdef 


f fef7a40 


00 00 f5 5f 00 00 


40 


08 


55 


55 


55 


55 


55 


55 


55 


55 


. .u_. . @ .UUUUUUUU 


f fef7a50 


55 55 55 55 55 55 


55 


55 


55 


55 


55 


55 


55 


55 


55 


55 


UUUUUUUUUUUUUUUU 


f fef7a60 


55 55 55 55 55 55 


55 


55 


00 


00 


00 


00 


00 


00 


00 


00 


UUUUUUUU 


ok 


























ok temp 


4000 free-mem 
























ok 



























An example of using memmap is shown below. 



ok 200 . 0000 sbus 1000 memmap ( virt ) 

ok 
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Using Defining Words 

The dictionary contains all the available Forth commands. Defining words are 
used to create new Forth commands. 

Defining words require two stack diagrams. The first diagram shows the stack 
effect when the new command is created. The second (or "Usage:") diagram 
shows the stack effect when that command is later executed. 

Table 4-7 lists the defining words that you can use to create dictionary entries. 



Table 4-7 Defining Words 



Command 


Stack Diagram 


Description 


: name 


(") 

Usage: ( ??? -- ? ) 


Start creating a new colon definition. 




(") 


Finish creating a new colon definition. 


alias new-name old-name 


(") 

Usage: ( ??? -- ? ) 


Create new-name with the same behavior as old-name. 


buffer: name 


( size -- ) 

Usage: ( -- adr64 ) 


Create a named array in temporary storage. 


constant name 


(n-) 

Usage: ( — n ) 


Define a constant (for example, 3 constant bar). 


2constant name 


( nl n2 -- ) 
Usage: ( -- nl n2 ) 


Define a 2-number constant. 


create name 


(") 

Usage: ( -- adrl6 ) 


Generic defining word. 


defer name 


(") 

Usage: ( ??? -- ? ) 


Define a word for forward references or execution vectors 
using code field address. 


does> 


( -- adrl6 ) 


Start the run-time clause for defining words. 


field name 


( offset size — offset+size ) 
Usage: ( adr — adr+offset ) 


Create a named offset pointer. 


struct 


(-0) 


Initialize for field creation. 


value name 


(n-) 

Usage: ( -- n ) 


Create a changeable, named 32-bit quantity. 


variable name 


(") 

Usage: ( -- adrl6 ) 


Define a variable. 
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You can use the defining word constant to create a name whose value will 
not change. A simple colon definition : foo 2 2 ; accomplishes a similar 
result. 



ok 72 constant red 

ok 

ok red . 

72 
ok 



value lets you assign a name to any number. Later execution of that name 
leaves the assigned value on the stack. The following example assigns a value 
of 22 to a word named foo, and then calls foo to use its assigned value in an 
arithmetic operation. 



ok 22 value foo 
ok foo 3 + . 

25 
ok 



The value can be changed with the dictionary compiling word is. For 
example: 



ok 43 value thisval 
ok thisval . 

43 

ok 10 is thisval 
ok thisval . 

10 
ok 



Commands created with value are convenient, because you do not have to 
use @ every time you want the number. 
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The defining word variable assigns a name to a 32-bit region of memory, 
which you can use to hold values as needed. Later execution of that name 
leaves the address of the memory on the stack. Typically @ and ! are used to 
read or write at that address. For example: 



ok variable bar 
ok 33 bar ! 
ok bar @ 2 + . 

35 
ok 



The defining word defer lets you change the execution of previously defined 
commands, by creating a slot which can be loaded with different behaviors at 
different times. For example: 



ok hex 

ok defer printit 

ok ['] .d is printit 

ok ff printit 

255 

ok : myprint ( n — ) . " It is " .h 

] . " in hex " ; 

ok [ ' ] myprint is printit 

ok ff printit 

It is ff in hex 
ok 
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Searching the Dictionary 

The dictionary contains all the available Forth commands. Table 4-8 lists some 
useful tools you can use to search the dictionary. 



Table 4-8 Dictionary Searching Commands 



Command 


Stack Diagram 


Description 


' name 


( " acf ) 


Find the named word in the dictionary. 

Returns the code field address. Use outside definitions. 


[ ' ] name 


( " acf ) 


Similar to ' but is used either inside or outside definitions. 


. calls 


( acf - ) 


Display a list of all words that call the word whose 
compilation address is acf. 


$f ind 


( adr len — adr len false 1 acf n ) 


Find a word, n = 0 if not found, n = 1 if immediate, 
n = -1 otherwise. 


find 


( pstr — pstr false 1 acf n ) 


Search for a word in the dictionary. The word to be found is 
indicated by pstr. n = 0 if not found, n = 1 if immediate, 
n = -1 otherwise. 


see thisword 


(") 


Decompile the named command. 


(see) 


(acf-) 


Decompile the word indicated by the code field address. 


sift 


( pstr - ) 


Display names of all dictionary entries containing the string 
pointed to by pstr. 


sifting ccc 


(") 


Display names of all dictionary entries containing the 
sequence of characters, ccc contains no spaces. 


words 


(") 


Display all visible words in the dictionary. 



see, used in the form see thisword, decompiles the specified command (that is, 
it shows the definition used to create thisword). The decompiled definition may 
sometimes be confusing, because some internal names may have been omitted 
from the PROM's symbol table to save space. 

The following screen is an example of how to use sifting. 



ok sifting input 

input-device input restore-input line-input input-line input- 
file 
ok 



words displays all the word (command) names in the dictionary, starting with 
the most recent definitions. 
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Compiling Data into the Dictionary 



The commands listed in Table 4-9 control the compilation of data into the 
dictionary. 

Table 4-9 Dictionary Compilation Commands 



Command 


Stack Diagram 


Description 


r 


(n-) 


Place a number in the dictionary. 


c, 


( byte -- ) 


Place a byte in the dictionary. 


w, 


( word — ) 


Place a 16-bit number in the dictionary. 


L, 


( long - ) 


Place a 32-bit number in the dictionary. 


[ 


(--) 


Begin interpreting. 


] 


(--) 


End interpreting, resume compilation. 


allot 


(n-) 


Allocate n bytes in the dictionary. 


>body 


( acf — apf ) 


Find parameter field address from compilation 
address. 


body> 


( apf — acf ) 


Find compilation address from parameter field 
address. 


compile 


(--) 


Compile next word at run time. 


[compile] name 


(--) 


Compile the next (immediate) word. 


forget name 


(--) 


Remove word from dictionary and all subsequent 
words. 


here 


( - adr ) 


Address of top of dictionary. 


immediate 


(--) 


Mark the last definition as immediate. 


is name 


(n-) 


Install a new action in a defer word or value . 


literal 


(n-) 


Compile a number. 


origin 


( — adr ) 


Return the address of the start of the Forth system. 


patch new-word old-word word-to-patch 


(--) 


Replace old-word with new-word in word-to-patch. 


(patch 


( new-n old-n acf — ) 


Replace old-n with new-n in word indicated 
by acf. 


recursive 


(--) 


Make the name of the colon definition being 
compiled visible in the dictionary, and thus allow 
the name of the word to be used recursively in its 
own definition. 


state 


( - adr ) 


Variable that is non-zero in compile state. 
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Displaying Numbers 



Basic commands to display stack values are shown in Table 4-10. 
Table 4-10 Basic Number Display 



Command 


Stack Diagram 


Description 




(n-) 


Display a number in the current base. 


. r 


( n size — ) 


Display a number in a fixed width field. 


. s 


(--) 


Display contents of data stack. 


showstack 


(--) 


Execute . s automatically before each ok prompt. 


u . 


(U-) 


Display an unsigned number. 


u . r 


( u size — ) 


Display an unsigned number in a fixed width field. 



The . s command displays the entire stack contents without disturbing them. It 
can be safely used at any time for debugging purposes. (This is the function 
that showstack performs automatically.) 



Changing the Number Base 



You can change the operating number base using the commands in Table 4-11. 
Table 4-11 Changing the Number Base 



Command 


Stack Diagram 


Description 


base 


( — adr ) 


Variable containing number base. 


binary 


(--) 


Set the number base to 2. 


decimal 


(--) 


Set the number base to 10. 


d# number 


(-n) 


Interpret the next number in decimal; base is unchanged. 


hex 


(--) 


Set the number base to 16. 


h# number 


(-n) 


Interpret the next number in hex; base is unchanged. 


.d 


(n-) 


Display n in decimal without changing base. 


.h 


(n-) 


Display n in hex without changing base. 
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The d# and h# commands are useful when you want to input a specific 
number in another base without explicitly changing the current base. For 
example: 



ok decimal (Changes base to decimal) 

ok 4 h# ff 17 2 

4 255 17 2 ok 



The . d and . h commands act like " . " but display the value in decimal or 
hexadecimal, respectively regardless of the current base setting. For example: 



ok 


hex 




ok 


ff . 


ff .d 


f f 


255 





Controlling Text Input and Output 

This section describes text input and output commands. These commands 
control strings or character arrays, and allow you to enter comments and 
control keyboard scanning. 

Table 4-12 lists commands to control text input. 



Table 4-12 Controlling Text Input 



Command 


Stack Diagram 


Description 


( ccc ) 


(") 


Begin a comment. 


\ rest-of-line 


(") 


Skip the rest of the line. 


ascii ccc 


( — char ) 


Get numerical value of first ASCII character of next word. 


expect 


( adr +n — ) 


Get a line of edited input from the assigned input device's 
keyboard; store at adr. 


key 


( — char ) 


Read a character from the assigned input device's keyboard. 


key? 


( " flag ) 


True if a key has been typed on the input device's keyboard. 


span 


( - adrl6 ) 


Variable containing the number of characters read by expect. 


word 


( char — pstr ) 


Collect a string delimited by char from input string and place 
in memory at pstr. 
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Comments are used with Forth source code (generally in a text file) to describe 
the function of the code. The ( (open parenthesis) is a command that begins a 
comment. Any character up to the closing parenthesis ) is ignored by the Forth 
interpreter. Stack diagrams are one example of comments using ( . 



Note - Remember to follow the ( with a space, so that it is recognized as 
a command. 



\ (backslash) indicates a comment terminated by the end of the line of text. 

key waits for a key to be pressed, then returns the ASCII value of that key on 
the stack. 

ascii, used in the form ascii x, returns on the stack the numerical code of 
the character x. 

key? looks at the keyboard to see whether the user has recently typed any key. 
It returns a flag on the stack: true if a key has been pressed and false 
otherwise. See "Conditional Flags" on page 73 for a discussion on the use of 
flags. 

Table 4-13 lists general-purpose text display commands. 



Table 4-13 Displaying Text Output 



Command 


Stack Diagram 


Description 


. " ccc" 


(--) 


Compile a string for later display. 


(or 


(--) 


Move the output cursor back to the beginning of the current line. 


cr 


(--) 


Terminate a line on the display and go to the next line. 


emit 


( char — ) 


Display the character. 


exit? 


( " flag ) 


Enable the scrolling control prompt: More [<space>, <cr>, q] ? 
The return flag is true if the user wants the output to be terminated. 


space 


(--) 


Display a space character. 


spaces 


( +n - ) 


Display +n spaces. 


type 


( adr +n — ) 


Display n characters. 
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cr sends a carriage-return character to the output. For example: 



ok 3 


44 


cr 5 . 


3 44 






5 






ok 







emit displays the letter whose ASCII value is on the stack. 



ok 


ascii 


a 


61 


ok 42 




61 


42 ok 


emit emit 


Ba 






ok 







Table 4-14 shows commands used to manipulate text strings. 
Table 4-14 Manipulating Text Strings 



Command 


Stack Diagram 


Description 




( adr len — ) 


Compile an array of bytes from adr of length len, 
at the top of the dictionary as a packed string. 


" ccc " 


( — adr len ) 


Collect an input stream string, either interpreted or 
compiled. Within the string, " ( 0 0 , f f . . . ) can be 
used to include arbitrary byte values. 


. ( ccc) 


(") 


Display a string immediately. 


-trailing 


( adr +nl - adr +n2 ) 


Remove trailing spaces. 


bl 


( — char ) 


ASCII code for the space character; decimal 32. 


count 


( pstr — adr +n ) 


Unpack a packed string. 


lcc 


( char — lowercase-char ) 


Convert a character to lowercase. 


left-parse- 
string 


( adr len char — adrR lenR adrL lenL ) 


Split a string at the given delimiter (which is 
discarded). 


pack 


( adr len pstr — pstr ) 


Make a packed string from adr len; place it at 
pstr. 


p" ccc" 


( " pstr ) 


Collect a string from the input stream; store as a 
packed string. 


upc 


( char — uppercase-char ) 


Convert a character to uppercase. 
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Some string commands specify an address (the location in memory where the 
characters reside) and a length (the number of characters in the string). Other 
commands use a packed string or pstr, which is a location in memory 
containing a byte for the length, immediately followed by the characters. The 
stack diagram for the command indicates which form is used. For example, 
count converts a packed string to an address-length string. 

The command . " is used in the form: . " string". It outputs text when needed. 
A " (double quotation mark) marks the end of the text string. For example: 



ok : testing 34 . . " This is a test" 55 . ; 

ok 

ok testing 

34 This is a test55 
ok 



Redirecting Input and Output 

Normally, your system uses a standard Sun keyboard for all user input, and a 
frame buffer with a connected display screen for most display output. (Server 
systems may use an ASCII terminal connected to a system serial port. For more 
information on how to connect a terminal to the system unit, see your system's 
installation manual.) You can redirect the input, the output, or both, to either 
one of the system's serial ports. This may be useful, for example, when 
debugging a frame buffer. 

Table 4-15 lists commands you can use to redirect input and output. 



Table 4-15 I/O Redirection Commands 



Command 


Stack Diagram 


Description 


input 


( device — ) 


Select device (ttya, ttyb, keyboard, or " device-specifier") for 
subsequent input. 


io 


( device — ) 


Select device for subsequent input and output. 


output 


( device — ) 


Select device (ttya, ttyb, screen, or " device-specifier") for 
subsequent output. 



The commands input and output temporarily change the current devices for 
input and output. The change takes place as soon as you enter a command; 
you do not have to reset your system. A system reset or power cycle causes the 
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input and output devices to revert to the default settings specified in the 
NVRAM configuration parameters input-device and output-device. 
These parameters can be modified, if needed (see Chapter 3, "Setting 
Configuration Parameters," for information about changing defaults). 

input must be preceded by one of the following: keyboard, ttya, ttyb, or 
device-specifier text string. For example, if input is currently accepted from the 
keyboard, and you want to make a change so that input is accepted from a 
terminal connected to the serial port TTYA, type: 



ok ttya input 

ok 



At this point, the Sun keyboard becomes non-functional (except for Stop-A), 
but any text entered from the terminal connected to TTYA is processed as 
input. All commands are executed as usual. 

To resume using the keyboard as the input device, use the terminal keyboard to 
type: 



ok keyboard input 

ok 



Similarly, output must be preceded by one of the following: screen, ttya, or 
ttyb. For example, if you want to send output to TTYA instead of the normal 
display screen, type: 



ok ttya output 



The screen does not show the answering ok prompt, but the terminal 
connected to TTYA shows the ok prompt and all further output as well. 

io is used in the same way, except that it changes both the input and output to 
the specified place. 
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Generally, input, output, and io take a device-specifier, which can be either a 
device path name or a device alias. The device must be specified as a Forth string, 
using double quotation marks ("), as shown in the two examples below: 



ok " /sbus/cgsix" output 



or: 



ok " screen" output 



In the preceding examples, ttya, screen, and keyboard are Forth words that 
put their corresponding device alias string on the stack. 

Keyboard Editor 

A keyboard line editor (similar to EMACS, a common text editor) and a history 
mechanism are also provided with the Forth Monitor. Use these powerful tools 
to re-execute previous commands without retyping them, to edit the current 
command line to fix typing errors, or to change previous commands. 

Table 4-16 list the line-editing commands available at the ok prompt. 

Table 4-16 Line Editor Commands 



Command 


Function 


Control-A 


Go to start of line. 


Control-B 


Go backward one character. 


Control-D 


Erase this character. 


Control-E 


Go to end of line. 


Control-F 


Go forward one character. 


Control-H 


Erase previous character (also Delete or Back Space keys). 


Control-K 


Erase forward, from here to end of line. 


Control-L 


Show command history list, then re-type line. 


Control-N 


Recall subsequent command line. 


Control-P 


Recall previous command line. 


Control-Q 


Quote next character (to type a control character). 



Using Forth Tools 



71 





Table 4-16 Line Editor Commands (Continued) 


Command 


Function 


Control-R 


Re-type line. 


Control-U 


Erase entire line. 


Control-W 


Erase previous word. 


Control-Y 


Insert save buffer contents before the cursor. 


Control-space 


Complete the current command. 


Control-/ 


Show all possible matches /completions. 


Control-? 


Show all possible matches /completions. 


Control- } 


Show all possible matches /completions. 


Esc-B 


Go backward one word. 


Esc-D 


Erase this portion of word, from here to end of word. 


Esc-F 


Go forward one word. 


Esc-H 


Erase previous portion of word (also Control-w). 



The command completion function saves you the work of typing very long 
command names. After you have typed the first part of the desired word, you 
can type Control-Space to tell the Forth Monitor to search the current 
dictionary of defined words. 

• If you have typed enough letters such that there is only one possible 
command starting with the typed letters, the rest of the command is filled in 
automatically. 

• If there is more than one possible match, the system echoes as many 
characters as can be determined for sure. 

• If there is no word starting with the given letters, those letters will be erased 
until there are possible candidates for the remaining letters. 

• The system beeps if it cannot determine an unambiguous match. 
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Conditional Flags 

Forth conditionals use flags to indicate true/false values. A flag can be 
generated in several ways, based on testing criteria. The flag can then be 
displayed from the stack with the word " . ", or it can be used as input to a 
conditional control command. Control commands can cause one behavior if a 
flag is true and another behavior if the flag is false. Thus, execution can be 
altered based on the result of a test. 

A 0 value indicates that the flag value is false. A -1 or any other non-zero 
number indicates that the flag value is true. (In hexadecimal, the value -1 is 
displayed asffffffff.) 

Table 4-17 lists commands that perform relational tests, and leave a true or 
false flag result on the stack. 



Table 4-17 Comparison Commands 



Command 


Stack Diagram 


Description 


< 


( nl n2 - flag ) 


True if nl < n2. 


<= 


( nl n2 - flag ) 


True if nl <= n2. 


<> 


( nl n2 - flag ) 


True if nl <> n2. 




( nl n2 - flag ) 


True if nl = n2. 


> 


( nl n2 - flag ) 


True if nl > n2. 


>= 


( nl n2 - flag ) 


True if nl >= n2. 


0< 


( n - flag ) 


True if n < 0. 


0<= 


( n - flag ) 


True if n <= 0. 


0<> 


( n - flag ) 


True if n <> 0. 


0 = 


( n - flag ) 


True if n = 0 (also inverts any flag). 


0> 


( n -- flag ) 


True if n > 0. 


0>= 


( n - flag ) 


True if n >= 0. 


between 


( n min max — flag ) 


True if min <= n <= max. 


false 


(-0) 


The value FALSE, which is 0. 


true 


( - -1 ) 


The value TRUE, which is -1. 


u< 


( ul u2 - flag ) 


True if ul < u2, unsigned. 


u<= 


( ul u2 - flag ) 


True if ul <= u2, unsigned. 
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Table 4-17 Comparison Commands (Continued) 



Command 


Stack Diagram 


Description 


u> 


( ul u2 -- flag ) 


True if ul > u2, unsigned. 


u>= 


( ul u2 -- flag ) 


True if ul >= u2, unsigned. 


within 


( n min max — flag ) 


True if min <= n < max. 



> takes two numbers from the stack, and returns true (-1) on the stack if the 
first number was greater than the second number, or returns false (0) 
otherwise. An example follows: 



ok 3 6 > . 




0 


(3 is not greater than 6) 


ok 





0= takes one item from the stack, and returns true if that item was 0 or 
returns false otherwise. This word inverts any flag to its opposite value. 



Control Commands 

The following sections describe words used within a Forth program to control 
the flow of execution. 

The if-then-else Structure 



The commands if, then, and else provide a simple control structure. 
The commands listed in Table 4-18 control the flow of conditional execution. 

Table 4-18 if-then-else Commands 



Command 


Stack Diagram 


Description 


else 


(") 


Execute the following code if if failed. 


if 


( flag -- ) 


Execute the following code if flag is true. 


then 


(--) 


Terminate if. . .then. . .else. 
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The format for using these commands is: 



flag 


if 


(do this if true) 




else 


(do this if false) 




then 


(continue normally) 


or 


flag 


if 


(do this if true) 




then 


(continue normally) 



The if command consumes a flag from the stack. If the flag is true (non-zero), 
the commands following the if are performed. Otherwise, the commands (if 
any) following the else are performed. 



ok : testit ( n — ) 

] 5 > if . " good enough " 

] else . " too small " 

] then 

] . " Done . " ; 

ok 

ok 8 testit 

good enough Done . 
ok 2 testit 

too small Done, 
ok 



Note - The ] prompt reminds you that you are part way through creating a 
new colon definition. It reverts back to ok after you finish the definition with a 
semicolon. 



Using Forth Tools 



75 



The case Statement 

A high-level case command is provided for selecting alternatives with 
multiple possibilities. This command is easier to read than deeply-nested 
if-then commands. 

Table 4-19 lists the conditional case commands. 



Table 4-19 case Statement Commands 



Command 


Stack Diagram 


Description 


case 


( selector — selector ) 


Begin a case . . . endcase conditional. 


endcase 


( selector 1 (empty) — ) 


Terminate a case . . . endcase conditional. 


endof 


(--) 


Terminate an of . . .endof clause within a 
case . . . endcase 


of 


( selector test-value — selector 1 {empty} ) 


Begin an of . . . endof clause within a case conditional. 



Here is a simple example of a case command: 



ok : testit ( testvalue — ) 

] case 0 of . " It was zero " endof 

] 1 of . " It was one " endof 

] f f of " Correct " endof 

] -2 of " It was minus-two " endof 

] ( default ) . " It was this value : " dup . 

] endcase . " All done . " ; 

ok 

ok 1 testit 

It was one All done, 
ok ff testit 
Correct All done, 
ok 4 testit 

It was this value: 4 All done, 
ok 



Note - The (optional) default clause can use the test value which is still on 
the stack, but should not remove it (use the "dup . " phrase instead of " . "). A 
successful o f clause automatically removes the test value from the stack. 
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The begin Loop 

A begin loop executes the same commands repeatedly until a certain 
condition is satisfied. Such a loop is also called a conditional loop. 

Table 4-20 lists commands to control the execution of conditional loops. 



Table 4-20 begin (Conditional) Loop Commands 



Command 


Stack Diagram 


Description 


again 


(") 


End a begin . . . again infinite loop. 


begin 


(") 


Begin a begin . . . while . . . repeat, begin . . . until , or 
begin. . .again loop. 


repeat 


(") 


End a begin . . . while . . . repeat loop. 


until 


( flag -- ) 


Continue executing a begin . . . until loop until flag is true. 


while 


( flag -- ) 


Continue executing a begin . . . while . . . repeat loop while 
flag is true. 






There are 


two general forms: 






begin 


any commands... flag until 






and 





begin any commands... flag while 

more commands repeat 



In both cases, the commands within the loop are executed repeatedly until the 
proper flag value causes the loop to be terminated. Then execution continues 
normally with the command following the closing command word (until or 
repeat). 

In the begin. . .until case, until removes a flag from the top of the stack 
and inspects it. If the flag is false, execution continues just after the begin, 
and the loop repeats. If the flag is true, the loop is exited. 

In the begin . . . while . . . repeat case, while removes a flag from the top of 
the stack and inspects it. If the flag is true, the loop continues by executing 
the commands just after the while. The repeat command automatically 
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sends control back to begin to continue the loop. If the flag is false when 
while is encountered, the loop is exited immediately; control goes to the first 
command after the closing repeat. 

An easy mnemonic for either of these loops is: If true, fall through. 
A simple example follows. 



ok begin 


4000 c@ 


key? until (repeat 


until any key is pressed) 


43 43 43 


43 43 43 


43 43 43 43 43 43 43 


43 43 43 43 43 


ok 









The loop starts by fetching a byte from location 4000 and displaying the value. 
Then, the key? command is called, which leaves a true on the stack if the 
user has pressed any key, and false otherwise. This flag is consumed by 
until and, if the value is false, then the loop continues. Once a key is 
pressed, the next call to key? returns true, and the loop terminates. 

Unlike many versions of Forth, the Forth Monitor allows the interactive use of 
loops and conditionals — that is, without first creating a definition. 

The do Loop 

A do loop (also called a counted loop) is used when the number of iterations of 
the loop can be calculated in advance. A do loop normally exits just before the 
specified ending value is reached. 

Table 4-21 lists commands to control the execution of counted loops. 



Table 4-21 do (Counted) Loop Commands 



Command 


Stack Diagram 


Description 


+ loop 


(n-) 


End a do . . . +loop construct; add n to loop index and return to do (if n 
< 0, index goes from start to end inclusive). 


?do 


( end start — ) 


Begin ?do . . . loop to be executed 0 or more times. Index goes from 
start to end-1 inclusive. If end = start, loop is not executed. 


?leave 


( nag - ) 


Exit from a do . . . loop if flag is non-zero. 


do 


( end start — ) 


Begin a do . . . loop. Index goes from start to end-1 inclusive. 
Example: 10 0 do i . loop (prints 0 1 2.. .d e f). 


i 


(-n) 


Loop index. 



78 



OpenBoot Command Reference — August 1994 



Table 4-21 do (Counted) Loop Commands (Continued) 



Command 


Stack Diagram 


Description 


j 


(-n) 


Loop index for next enclosing loop. 


leave 


(--) 


Exit from do . . . loop . 


loop 


(--) 


End of do . . . loop . 



The following screen shows several examples of how loops are used. 



ok 10 5 do i . loop 

56789abcdef 
ok 

ok 2000 1000 do i . i c@ . cr i c@ ff = if leave then 4 +loop 

1000 23 
1004 0 
1008 fe 
100c 0 
1010 78 
1014 ff 

ok : scan ( byte — ) 

6000 5000 (Scan memory 5000 - 6000 for bytes not equal to the specified byte) 

do dup i c@ <> ( byte error? ) 

if i . then ( byte ) 
loop 

drop ( the original byte was still on the stack, discard it ) 

r 

ok 55 scan 

5005 5224 5f99 

ok 6000 5000 do i i c! loop (Fill a region of memory with a stepped pattern) 

ok 

ok 500 value testloc 

ok : testl6 ( — ) 1.0000 0 ( do 0-ffff ) (Write different 16-bit values to a location) 
do i testloc w! testloc w@ i <> ( error? ) (Also check the location) 
if . " Error - wrote " i . . " read " testloc w@ cr 

leave ( exit after first error found ) (This line is optional) 
then 
loop 

r 

ok testl6 

ok 6000 is testloc 
ok testl6 

Error - wrote 200 read 300 
ok 
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Additional Control Commands 

Table 4-22 contains descriptions of additional program execution control 
commands. 



Table 4-22 Program Execution Control Commands 



Command 


Stack Diagram 


Description 


abort 


(--) 


Abort current execution and interpret keyboard commands. 


abort" ccc" 


( abort? -- ) 


If flag is true, abort and display message. 


eval 


( adr len — ) 


Interpret Forth source from an array. 


execute 


(act-) 


Execute the word whose code field address is on the stack. 


exit 


(--) 


Return from the current word. Cannot be used in counted loops. 


quit 


(--) 


Same as abort, but leave stack intact. 



abort causes immediate termination and returns control to the keyboard, 
abort" is similar to abort but is different in two respects, abort" removes a 
flag from the stack and only aborts if the flag is true. Also, abort " prints any 
desired message when the abort takes place. 

eval takes a string from the stack (specified as an address and a length). The 
characters in that string are then interpreted as if they were entered from the 
keyboard. If a Forth text file has been loaded into memory (see Chapter 5, 
"Loading and Executing Programs,"), then eval can be used to compile the 
definitions contained in the file. 
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Loading and Execu ting Programs 5 = 



The Forth Monitor provides several methods for loading and executing a 
program on the machine. These methods load a file into memory from 
Ethernet, a hard disk, a floppy disk, and serial port A, and support the 
execution of Forth, FCode, and binary executable programs. 

Commands for loading files from various sources are listed in Table 5-1. 



Table 5-1 File Loading Commands 



Command 


Stack Diagram 


Description 


?go 


(") 


Execute Forth, FCode or binary programs. 


boot [specifiers] -h 


(") 


Load file from specified source. 


byte-load 


( adr span — ) 


Interpret loaded FCode binary file, span is usually 1. 


dl 


(") 


Load a Forth file over a serial line with TIP and interpret. Type: 

~C cat filename 

A -D 


dlbin 


(") 


Load a binary file over a serial line with TIP. 
Type: ~C cat filename 


dload filename 


( adr - ) 


Load the specified file over Ethernet at the given address. 


eval 


( adr len — ) 


Interpret loaded Forth text file. 


go 


(--) 


Begin executing a previously-loaded binary program, or resume 
executing an interrupted program. 
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Table 5-1 File Loading Commands (Continued) 



Command 


Stack Diagram 


Description 


init -program 


(") 


Initialize to execute a binary file. 


load device-specifier argument 


(") 


Load data from specified device into memory at the address given 

by load-base. 


load-base 


( -- adr ) 


Address at which load places the data it reads from a device. 



Using dload to Load from Ethernet 

dload loads files over Ethernet at a specified address, as shown below. 



ok 4000 dload filename 



In the above example, filename must be relative to the server's root. Use 4000 
(hex) as the address for dload input, dload uses the trivial file transfer 
protocol (TFTP), so the server may need to have its permissions adjusted for 
this to work. 

Forth Programs 

Forth programs loaded with dload must be ASCII files beginning with the two 
characters "\ " (backslash and blank). To execute the loaded Forth program, 
type: 



ok 4000 file-size @ eval 



In the above example, file-size contains the size of the loaded image. 
FCode Programs 

FCode programs loaded with dload must be a . out files. To execute the 
loaded FCode program, type: 

ok 4000 1 byte-load 
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byte- load is used by the OpenBoot firmware to interpret FCode programs on 
expansion boards such as SBus. The l in the example is a specific value of a 
parameter that specifies the separation between FCode bytes in the general 
case. Since dload loads into system memory l is the correct spacing. 

Binary Executables 

Executable binary programs loaded with dload are a . out files and must be 
linked to run dload's input address (4000) or be position independent. To 
execute the binary program, type: 



ok go 



To run the program again, type: 



ok init-program go 



dload does not use intermediate booters (unlike the boot command). Thus, 
any symbol information included in the a . out file is available to the Forth 
Monitor's symbolic debugging capability. (See Chapter 6, "Debugging," for 
more information on symbolic debugging.) 

Using boot to Load from Hard Disk, Floppy Disk, or Ethernet 

You can also load and execute a program with boot, the command normally 
used to boot the operating system, boot has the following format: 



ok boot [device-specifier] [filename] -h 



device-specifier is either a full device path name or a device alias. (See Chapter 1, 
"Overview," for information on device path names and aliases.) 

For a hard disk or floppy partition, filename is relative to the resident file 
system. (See Appendix B, "Building A Bootable Floppy Disk," for information 
on creating a bootable floppy disk.) For Ethernet, filename is relative to the 
system's root partition on its root server. In both cases, the leading / must be 
omitted from the file path. 
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The -h flag specifies that the program should be loaded, but not executed. 

boot uses intermediate booters to accomplish its task. When loading from a 
hard disk or floppy disk, the OpenBoot firmware first loads the disk's boot 
block, which in turn loads a second-level booter. When loading over Ethernet, 
the firmware uses TFTP to load the second-level booter. filename and -h are 
passed to these intermediate booters. 

Forth Programs 

Forth programs are ASCII source files that must be converted to the file format 
required by the secondary boot program. A utility called f akeboot is 
available from the SBus Support Group at Sun to perform this conversion. 
After the file is loaded into memory, it can be executed using the command 

eval. 

For instance, if the file is loaded to address 0x4010, and runs for 934 bytes, 
type: 



ok 4010 d# 934 eval 



FCode Programs 

FCode programs produced by a Tokenizer (which creates FCode programs) 
may need to be converted to the file format of the secondary boot program, 
f akeboot may be useful in this process. Once the file is in memory, execute it 
using the byte-load command. 

For example, assuming the file is loaded to address 0x4030, type: 



ok 4030 1 byte-load 



Binary Executables 

A binary program other than the operating system can also be loaded and 
executed as follows: 



ok go 



go is needed since the boot command includes -h. 
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Using dl to Load Forth Over Serial Port A 



Forth programs loaded with dl must be ASCII files. 

To load the file over the serial line, connect the system's serial port A to a 
machine that is able to transfer a file on request. One method is to set up a TIP 
window on another Sun system. (See Appendix A, "Setting Up a TIP 
Connection," for information on this procedure.) The following example 
assumes a TIP window setup. 

1. At the ok prompt, type: 



ok dl 



2. In the TIP window of the other system, send the file, and follow it with a 
Control-D to signal the end of the file. 



~C (local command) cat filename 
(Away two seconds) 
A -D 



The ok prompt appears on the screen of the system to which the file is loaded. 

ell normally loads the file at 4000 (hex). The file is automatically interpreted 
after it is loaded. 

Using dlbin to Load FCode or Binary Over Serial Port A 

FCode and binary programs loaded with dlbin must be a . out files, dlbin 
loads the files at the entry point indicated in the a . out header. Link binary 
files for 4000 (hex). Recent versions of the FCode Tokenizer create an a . out 
file with entry point 4000. 

To load the file over the serial line, connect the system's serial port A to a 
machine that is able to transfer a file on request. The following example 
assumes a TIP window setup. (See Appendix A, "Setting Up a TIP 
Connection," for information on this procedure.) 
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1. At the ok prompt, type: 



ok dlbin 



2. In the TIP window of the other system, send the file: 



~C (local command) cat filename 

(Away two seconds) 



The ok prompt appears on the screen of the system to which the file is loaded. 
To execute an FCode program, type: 



ok 4000 1 byte-load 

ok 



To execute a binary program, type: 



ok go 



OpenBoot Command Reference — August 1994 



Debugging 



The OpenBoot firmware provides debugging tools that include a disassembler, 
register display commands, a symbolic debugger, and breakpoint commands. 

Using the Disassembler 

The built-in disassembler translates the contents of memory into equivalent 
SPARC assembly language. 

Table 6-1 lists commands that disassemble memory into equivalent opcodes. 



Table 6-1 Disassembler Commands 



Command 


Stack Diagram 


Description 


+dis 


(") 


Continue disassembling where the last disassembly left off. 


dis 


( adr - ) 


Begin disassembling at the given address. 



dis begins to disassemble the data content of any desired location. The system 
pauses either if any key is pressed while disassembly is taking place or after 
every page of output. At that point, disassembly can be continued or stopped. 
Disassembly stops automatically when a call or jmp opcode is encountered. 
You can use the +dis command to continue disassembling at the location 
where the last disassembly stopped. 

Memory addresses are normally shown in hexadecimal. However, if a symbol 
table is present, memory addresses are displayed symbolically whenever 
possible. 
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Displaying Registers 



You can enter the Forth Monitor from the middle of an executing program as a 
result of a program crash, a user abort with Stop-A, or an encountered 
breakpoint. (Breakpoints are discussed on page 89.) In all these cases, the Forth 
Monitor automatically saves all the CPU data register values in a buffer area. 
These values can then be inspected or altered for debugging purposes. 

Table 6-2 lists the SPARC register commands. 

Table 6-2 SPARC Register Commands 



Command 


Stack Diagram 


Description 


%f0 through %f31 


( — value ) 


Return the value in the given floating point register. 


%fsr 


( — value ) 


Return the value in the given floating point register. 


%g0 through %g7 


( — value ) 


Return the value in the given register. 


% i 0 through % i 7 


( — value ) 


Return the value in the given register. 


%L0 through %L7 


( — value ) 


Return the value in the given register. 


%o0 through %o7 


( — value ) 


Return the value in the given register. 




( — value ) 


Return the value in the given register. 


%y %wim %tbr 


( — value ) 


Return the value in the given register. 


. f registers 


(") 


Display values in %f 0 through %f 31 . 


. locals 


(") 


Display the values in the i, L and o registers. 


. psr 


(") 


Formatted display of the %psr data. 


. registers 


(") 


Display values in %g0 through %g7, plus %pc, %npc, %psr, %y, %wim, %tbr . 


. window 


( window# — ) 


Same asw .locals; display the desired window. 


ctrace 


(") 


Display the return stack showing C subroutines. 


set-pc 


( value — ) 


Set %pc to the given value, and set %npc to (value+4). 


to regname 


( value — ) 


Change the value stored in any of the above registers. 
Use in the form: value to regname. 


W 


( window* — ) 


Set the current window for displaying %ix, %Lx, or %ox. 



After you inspect the values, you can continue program execution by typing 
the go command. The saved register values are copied back into the CPU, and 
execution resumes at the location specified by the saved program counter. 
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These saved register values can be changed, if needed, with the to command. 
When execution is resumed, the changed values are copied back into the CPU 
and used. 

If you change %pc with to, you should also change %npc. (It is easier to use 
set-pc, which changes both registers automatically.) 

For the w and . window commands, a window value of 0 usually specifies the 
current window — that is, the active window for the subroutine where the 
program was interrupted. A value of 1 specifies the window for the caller of 
this subroutine, 2 specifies the caller's caller, and so on, up to the number of 
active stack frames. The default starting value is 0. 

Breakpoints 

The Forth Monitor provides a breakpoint capability to assist in the 
development and debugging of standalone programs. (Programs that run 
under the operating system generally do not use this feature, but use other 
debuggers designed to run under the operating system.) The breakpoint 
feature lets you stop the test program at desired points. After program 
execution has stopped, registers or memory can be inspected or changed, and 
new breakpoints can be set or cleared. You can resume program execution with 
the go command. 

Table 6-3 lists the breakpoint commands that control and monitor program 
execution. 



Table 6-3 Breakpoint Commands 



Command 


Stack Diagram 


Description 


+bp 


( adr - ) 


Add a breakpoint at the given address. 


-bp 


( adr - ) 


Remove the breakpoint at the given address. 


— bp 


(--) 


Remove the most-recently-set breakpoint. 


.bp 


(--) 


Display all currently set breakpoints. 


. breakpoint 


(--) 


Perform a specified action when a breakpoint occurs. This word can be altered to 
perform any desired action. For example, to display registers at every breakpoint, 
type: ['] .registers is . breakpoint. The default behavior is 
. instruction. To perform multiple behaviors, create a single definition which 
calls all desired behaviors, then load that word into .breakpoint. 


. instruction 


(--) 


Display the address, opcode for the last-encountered breakpoint. 
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Table 6-3 Breakpoint Commands (Continued) 



Command 


Stack Diagram 


Description 


. step 


(--) 


Perform a specified action when a single step occurs (see .breakpoint). 


bpof f 


(--) 


Remove all breakpoints. 


finish-loop 


(--) 


Execute until the end of this loop. 


go 


(--) 


Continue from a breakpoint. This can be used to go to an arbitrary address by 
setting up the processor's program counter before issuing go. 


gos 


(n-) 


Execute go n times. 


hop 


(--) 


(Like the step command.) Treat a subroutine call as a single instruction. 


hops 


(n-) 


Execute hop n times. 


return 


(--) 


Execute until the end of this subroutine. 


returnL 


(--) 


Execute until the end of this leaf subroutine. 


skip 


(--) 


Skip (do not execute) the current instruction. 


step 


(--) 


Single-step one instruction. 


steps 


(n-) 


Execute step n times. 


till 


( adr — ) 


Execute until the given address is encountered. Equivalent to +bp go . 



To debug a program using breakpoints, use the following procedure. 

1. Load the test program into memory at location 4000 (hex). 

See Chapter 5, "Loading and Executing Programs," for more information. 
Using dload is generally best, since the symbol table for the program is 
preserved, boot -h also works if the program is not available over 
Ethernet. 

The values for %pc and all other registers are initialized automatically. 

2. (Optional) Disassemble the downloaded program to verify a properly- 
loaded file. 

3. Begin single-stepping the test program using the step command. 
You can also set a breakpoint, then execute (for example, using the 
commands 4 02 0 +bp and go) or perform other variations. 
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The Forth Source-level Debugger 

The Forth Source-level Debugger allows single-stepping and tracing of Forth 
programs. Each "step" represents the execution of one Forth word. 

The debugger commands are shown in Table 6-4. 



Table 6-4 Forth Source-level Debugger Commands 



Command 


Description 


C 


"Continue". Switch from stepping to tracing, thus tracing the remainder of the execution of the word 
being debugged. 


D 


"Down a level". Mark for debugging the word whose name was just displayed, then execute it. 


F 


Start a subordinate Forth interpreter. When that interpreter exits (with resume), control returns to the 
debugger at the place where the F command was executed. 


Q 


"Quit". Abort the execution of the word being debugged and all its callers and return to the command 
interpreter. 


u 


"Up a level". Un-mark the word being debugged, mark its caller for debugging, and finish executing 
the word that was previously being debugged. 


debug name 


Mark the named Forth word for debugging. Enter the Forth Source-level Debugger with any 
subsequent attempts to execute that word. After executing debug, the execution speed of the system 
may decrease until debugging is turned off with debug-off. (Do not debug basic Forth words such 
as ".".) 


debug-off 


Turn off the Forth Source-level Debugger so that no word is being debugged. 


resume 


Exit from a subordinate interpreter, and go back to the stepper (see the F command in this table). 


stepping 


Set "step mode" for the Forth Source-level Debugger, allowing the interactive, step-by-step execution 
of the word being debugged. Step mode is the default. 


tracing 


Set "trace mode" for the Forth Source-level Debugger. This traces the execution of the word being 
debugged, while showing the name and stack contents for each word called by that word. 


Space 


Execute the word just displayed and proceed to the next word. 



Before the execution of each word called by the word that is being debugged, 
the contents of the stack are displayed, followed by the name of the word that 
is about to be executed. In trace mode, that word is then executed, and the 
process continues with the next word called by the debugged word. In step 
mode (the default), the user controls execution: before the execution of each 
word called by the debugged word, the user is prompted for one of the 
specified keystrokes. 
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The ft race command shows the sequence of Forth words that were being 
executed at the time of the last exception. An example of ftrace follows. 



ok : testl 1 ! ; 

ok : test2 1 testl ; 

ok test2 

Memory address not aligned 
ok ftrace 

! Called from testl at ffeacc5c 
testl Called from test2 at ffeacc6a 
(ffe8b574) Called from (interpret at ffe8b6f8 
execute Called from catch at ffe8a8ba 

f fefef f 0 

0 

f f ef ebdc 

catch Called from (fload) at ffe8ced8 
0 

(fload) Called from interact at ffe8cf74 
execute Called from catch at ffe8a8ba 

f fefef d4 

0 

f f ef ebdc 

catch Called from (quit at ffe8cf98 



In this example, test 2 calls testl, which tries to store a value to an 
unaligned address. This results in the exception: Memory address not 
aligned. 

The first line of ftrace's output shows the last command that caused the 
exception to occur. The next lines show locations from which the subsequent 
commands were being called. 

The last thirteen lines are usually the same in any ftrace output, because that 
is the calling sequence in effect when the Forth interpreter interprets a word 
from the input stream. 



OpenBoot Command Reference — August 1994 



Setting Up a TIP Connection 



You can use the TTYA or TTYB ports on your SPARC system to connect to a 
second Sun workstation. This workstation can be either the same type of 
SPARC system or a different type of Sun workstation or server system. By 
connecting two systems in this way you can use a shell window on the Sun 
workstation as a terminal to your SPARC system. (See the on-line tip 
manpage for detailed information about terminal connection to a remote host.) 

The TIP method is recommended (over simply connecting to a dumb terminal), 
since it lets you use windowing and operating system features when working 
with the boot PROM. A communications program or another non-Sun 
computer can be used in the same way if the program can match the output 
baud rate used by the PROM TTY port. 



Note - In the following pages, "SPARC system" refers to your system, and 
"Sun workstation" refers to the system you are connecting to your system. 
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Use the following procedure to set up the TIP connection. 

1 . Connect the Sun workstation TTYB serial port to your SPARC system TTYA 
serial port using a serial connection cable. Use a 3-wire Null Modem Cable, 
and connect wires 3-2, 2-3, and 7-7. (Refer to your system installation 
manual for specifications on null modem cables.) 

2. At the Sun workstation, add the following lines to the /etc/remote file. 
If you are running a pre-Solaris 2.0 version of the operating environment, 
type: 



hardwire : \ 

:dv=/dev/ttyb:br#9 60 0 : el = A C A S A Q A U A D : ie=%$ :oe= A D : 



If you are running version 2.0 or 2.1 of the Solaris operating environment, 
type: 



hardwire : \ 

:dv=/dev/term/b:br#9 60 0 :el= A C A S A Q A U A D : ie=%$ :oe= A D : 



3. In a Shell Tool window on the Sun workstation, type: 



hostname% tip hardwire 

connected 



The Shell Tool window is now a TIP window directed to the Sun 
workstation TTYB. 



Note - Use a Shell Tool, not a Command Tool; some TIP commands may not 
work properly in a Command Tool window. 



4. At your SPARC system, enter the Forth Monitor so that the ok prompt is 
displayed. 

If you do not have a video monitor attached to your SPARC system, connect 
the SPARC system TTYA to the Sun workstation TTYB and turn on the 
power to your SPARC system. Wait for a few seconds, and press Stop-A to 
interrupt the power-on sequence and start the Forth Monitor. Type n to get 
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to the ok prompt. Unless the system is completely inoperable, the Forth 
Monitor is enabled, and you can continue with the next step in this 
procedure. 

5. If you need to redirect the standard input and output to TTYA, type: 



ok ttya io 



There will be no echoed response. 

6. Press Return on the Sun workstation keyboard. The ok prompt appears in 
the TIP window. 

Typing ~# in the TIP window is equivalent to typing St op -A at the SPARC 
system. 



Note - Do not type Stop-A from a Sun workstation being used as a TIP 
window to your SPARC system. Doing so will abort the operating system on 
the workstation. (If you accidentally type Stop-A, you can recover by 
immediately typing either c at the > prompt or go at the ok prompt.) 



7. When you are finished using the TIP window, end your TIP session and exit 
the window: 

a. Redirect the input and output to the screen and keyboard, if needed. 

b. In the TIP window, type: 

ok ~ . 

hostnamel 



Note - When entering ~ (tilde character) commands in the TIP window, 

~ must be the first character entered on the line. To ensure that you are at the 

start of a new line, press Return first. 



Setting Up a TIP Connection 
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Common Problems with TIP 

This section describes solutions for TIP problems occurring in pre-Solaris 2.0 
operating environments. 

Problems with TIP may occur if: 

• The lock directory is missing or incorrect. 

There should be a directory named /usr/spool/uucp. The owner should 
be uucp and the mode should be drwxr-sr-x. 

• TTYB is enabled for logins. 

The status field for TTYB (or the serial port you are using) must be set to 

of f in /etc/ttytab. Be sure to execute kill -HUP 1 (see init ( 8 ) ) as 
root if you have to change this entry. 

• /dev/ttyb is inaccessible. 

Sometimes, a program will have changed the protection of /dev/ttyb (or 
the serial port you are using) so that it is no longer accessible. Make sure 
that /dev/ttyb has the mode set to crw-rw-rw- . 

• The serial line is in tandem mode. 

If the TIP connection is in tandem mode, the operating system sometimes 
sends XON ( A S) characters (particularly when programs in other windows 
are generating lots of output). The XON characters are detected by the Forth 
word key?, and can cause confusion. The solution is to turn off tandem 
mode with the ~s ! tandem TIP command. 

• The . cshrc file generates text. 

TIP opens a sub-shell to run cat, thus causing text to be attached to the 
beginning of your loaded file. If you use dl and see any unexpected output, 
check your .cshrc file. 
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Building A Bootable Floppy Disk B = 



The instructions in this appendix show how to build a floppy diskette from 
which you can boot programs. You should use a high density (HD, not DD) 
diskette. Two sets of instructions are provided: 

• Page 98 describes the procedure for systems using pre-Solaris 2.0 operating 
environments. 

• Page 99 describes the procedure for systems using the Solaris 2.0 or 2.1 
operating environments. 
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Procedure for the Pre-Solaris 2.0 Operating Environment 

Use the following procedure if you are using a pre-Solaris 2.0 version of the 
operating system. 

1 . Format the diskette, 
hostnamel fdformat 

2. Create the diskette's file systems, 
hostnamel /usr/etc/newf s /dev/rfdOa 

3. Mount the diskette. 

hostname! mount /dev/fdOa /mnt 

4. Copy the second-level disk booter to the diskette, 
hostnamel cp /boot /mnt 

5. Install a boot block on the floppy. 

hostname! /usr/mdec/installboot /mnt/boot /usr/mdec/bootf d /dev/rfdOa 

6. Copy the file you want to boot to /mnt. 

7. Unmount the diskette and remove it from the drive. 

hostname! umount /mnt 
hostname! eject floppy 
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Procedure for the Solaris 2.0 or 2.1 Operating Environment 

Use the following procedure if you are using the Solaris 2.0 or 2.1 operating 
environment. 

1 . Format the diskette, 
hostnamel fdformat 

2. Create the diskette's file systems, 
hostnamel /usr/sbin/newf s /dev/rdiskette 

3. Mount the diskette. 

hostname! mount /dev/diskette /mnt 

4. Copy the second-level disk booter to the diskette, 
hostnamel cp /ufsboot /mnt 

5. Install a boot block on the floppy. 

hostnamel /usr/sbin/installboot /usr/lib/f s/uf s/bootblk /dev/rdiskette 

6. Copy the file you want to boot to /mnt. 

7. Unmount the diskette and remove it from the drive. 

hostname! umount /mnt 
hostnamel eject floppy 
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Unsupported Commands C = 



Some features of the OpenBoot firmware may not be available in early systems. 
If you want to use a documented command that is not available in your 
system, refer to this appendix for a possible workaround. 



Table C-l Workarounds for Unsupported Commands 



Command 


Availability 


Workaround 


" embedded bytes 


Not supported in 
earlier systems. 


Use other array-creation mechanisms, such as 
alloc-mem and c, . 


. attributes 


Not supported until 
OpenBoot 2.0. 


A loadable "showdevs" utility, which provides some of this 
functionality, is available from the Sun SBus Support Group. 


alloc-mem 


See workaround. 


Pre-2.0, size is restricted to total remaining Forth dictionary space. 
Using more than several hundred bytes is dangerous. 
Use dma-alloc ( size -- virt ) instead. 


boot-device 
boot-file 


Not supported until 
OpenBoot 2.0. 


Use boot-f rom to indicate boot device and boot file. 


cd 


Not supported until 
OpenBoot 2.0. 


A loadable "showdevs" utility, which provides some of this 
functionality, is available from the Sun SBus Support Group. 


Command completion 


Not supported in 
early systems. 


Type the entire command name. 


cpeek 
cpoke 


Not supported in 
early systems. 


"probe" words exist in early systems to provide a similar 
functionality, as: 

cprobe ( adr — ok? ) Test for data exception using c@. 


d! 

d? 
d@ 


Not supported in 
early systems. 


Use combinations of 32-bit accesses. 
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Table C-l Workarounds for Unsupported Commands (Continued) 



Command 


Availability 


Workaround 


diag-device 
diag-f ile 


Not supported until 
OpenBoot 2.0. 


Use boot-f rom-diag to indicate diagnostic boot device and boot 
file. 


lpeek 
lpoke 


Not supported in 
early systems. 


"probe" words exist in early systems to provide a similar 
functionality, as: 

lprobe ( adr32 — ok? ) Test for data exception using 1@. 


Is 


Not supported until 
OpenBoot 2.0. 


A loadable "showdevs" utility which provides some of this 
functionality is available from the Sun SBus Support Group. 


NVRAMRC 


Not supported until 
OpenBoot 2.0. 


No workaround. A different version exists in OpenBoot 1.6; do not 
use this version. 


nvalias 
nvunalias 


Not supported until 
OpenBoot 2.6. 


Manually edit NVRAMRC. 


nodef ault-bytes 


Not supported until 
OpenBoot 2.0. 


No workaround. 


patch 


See workaround. 


Pre-2.6, patch would patch words but not numbers within 
definitions. To patch numbers, use : 
npatch word-to-patch ( new-n old-n -- ). 


probe-scsi-all 


Not supported until 
OpenBoot 2.6. 


No workaround. 


pwd 


Not supported until 
OpenBoot 2.0. 


A loadable "showdevs" utility, which provides some of this 
functionality, is available from the Sun SBus Support Group. 


show-devs 


Not supported until 
OpenBoot 2.0. 


A loadable "showdevs" utility, which provides some of this 
functionality, is available from the Sun SBus Support Group. 


show-sbus 


Not supported until 
OpenBoot 2.3. 


Use: 

ok cd / sbus 

ok Is 

(Similar information is presented, but in a different format.) 






showstack 


Does not toggle (turn 
off) until OpenBoot 
2.6. 


To turn off showstack, either reset the system or type: 

[ x ] noop is status 


spaced? 


Not supported until 
OpenBoot 2.6. 


Use spacedO and " . " 


Stop-F 
Stop-D 
Stop-N 


Not supported until 
OpenBoot 2.0. 


No workaround. 
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Table C-l Workarounds for Unsupported Commands (Continued) 



Command 


Availability 


Workaround 


tost ocococ 


Not supported until 
OpenBoot 2.0. 


It is possible to test certain devices on OpenBoot 1.x systems with: 
test-memory ( — ) (similar to: test /memory). 
Some plug-in devices can also be tested by directly entering the 
appropriate test name (on OpenBoot 1.x only). 


User-added device 
aliases 


Not supported until 
OpenBoot 2.0. 


No workaround. 


watch-net 


Not supported in 
OpenBoot 1.3 
through 2.2. 


No workaround. 


wpeek 
wpoke 


Not supported in 
early systems. 


"probe" words exist in early systems to provide a similar 
functionality, as: 

wprobe ( adrl6 — ok? ) Test for data exception using w@. 



Unsupported Commands 



103 




104 



OpenBoot Command Reference — August 1994 



Troubleshooting Guide 



What do you do if your system fails to boot properly? This appendix discusses 
some common failures and ways to alleviate them. 

Power-on Initialization Sequence 

Familiarize yourself with the system power-on initialization messages. You can 
then identify problems more accurately because these messages show you the 
types of functions the system performs at various stages of system start-up. 
They also show the transfer of control from POST to the OpenBoot firmware to 
the Booter to the kernel. 

The example that follows shows the OpenBoot initialization sequence in a 
SPARCstation 10 system. The messages before the banner appear on TTYA 
only if the diag-switch? parameter is true. 



Note - The displayed kernel messages may vary depending on the version of 
the operating system you are using. 
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ttya initialized 




(At this point / POST has finished cxccut ion 








and transferred control to the OpenBoot firmware) 


Cpu #0 TI, TMS390Z50 




(Probe CPU module) 


Cpu #1 Nothing 


there 






Cpu #2 Nothing 


there 






Cpu #3 Nothing 


there 






Probing Memory 


Bank #0 16 Megabytes of DRAM 


(Probe memory) 


Probing Memory 


Bank #1 Nothing 


there 




Probing Memory 


Bank #2 Nothing 


there 




Probing Memory 


Bank #3 Nothing 


there 




Probing Memory 


Bank #4 Nothing there 




Probing Memory 


Bank #5 Nothing 


there 




Probing Memory 


Bank #6 Nothing 


there 




Probing Memory 


Bank #7 Nothing 


there 










( Before p rob i n g the de v i oe s the f i rmwa re executes 








NVRAMRC commands ~ if Tj.ss~r1v2r3.m1rc? is tirus — 








and checks for St op - x commands 








Keyboard LED s flash ) 


Probing /iommu( 


f , e0000000/sbus( 


f,e0001000 at f , 0 


(Probe devices) 


espdma esp 


sd st ledma le 


SUNW,bpp SUNW,DBRIa 




Probing /iommu( 


f , eOOOOOOO/sbusC 


f,e0001000 at 0,0 




Nothing there 






Probing /iommu( 


f , e0000000/sbus( 


f,e0001000 at 1,0 




Nothing there 






Probing /iommu( 


f , e0000000/sbus( 


f,e0001000 at 2,0 




Nothing there 






Probing /iommu( 


f , e0000000/sbus( 


f,e0001000 at 3,0 




Nothing there 






SPARCstation 10 (1 X 390Z50), Keyboard Present 


(Display banner) 


ROM Rev. 2.10, 


16 MB memory installed, Serial #4194577. 




Ethernet address 8 : 0 : 20 : 10 : 61 :b5, Host ID: 72400111. 




Boot device: /iommu/sbus/espdma@f , 400000/esp@f, 800000/ 


(The firmware is TFTP-ing in the boot program) 


sd@3,0 File and args : 




(Control is transferred to Booter after 








this message is displayed) 


root on /iommu( 


f , e0000000/sbus( 


f , e0001000/espdma@ 


(Booter starts executing) 


f , 4 0 00 00/esp@f , 800000/sd@3 


,0:a fstype 4.2 




Boot : vmunix 








Size: 142 54 0 8+4 3 6752+17 62 8 8 bytes 


(Control is passed to the Kernel after 








this message is displayed) 


Viking/NE: PAC 


ENABLED 




(Kernel starts to execute) 








(More kernel messages) 
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Emergency Procedures 

Table D-l describes commands that are useful in some failure situations. When 
issuing any of these commands, hold down the keys immediately after turning 
on the power to your system, and keep them pressed for a few seconds until 
the keyboard LEDs flash. 



Table D-l Emergency Keyboard Commands 



Command 


Description 


Stop 


Bypass POST. This command does not depend on security-mode. (Note: some systems bypass 
POST as a default; in such cases, use Stop-D to start POST.) 


Stop-A 


Abort. 


Stop-D 


Enter diagnostic mode (set diag-switch? to true). 


Stop-F 


Enter Forth on TTYA instead of probing. Use f exit to continue with the initialization sequence. 
Useful if hardware is broken. 


Stop-N 


Reset NVRAM contents to default values. 



Note - These commands are disabled if the PROM security is on. Also, if your 
system has full security enabled, you cannot apply any of the suggested 
commands unless you have the password to get to the ok prompt. 



Preserving Data After a System Crash 

The sync command forces any information on its way to the hard disk to be 
written out immediately. This is useful if the operating system has crashed, or 
has been interrupted without preserving all data first. 

sync actually returns control to the operating system, which then performs the 
data saving operations. After the disk data has been synchronized, the 
operating system begins to save a core image of itself. If you do not need this 
core dump, you can interrupt the operation with the Stop-A key sequence. 
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Common Failures 

This section describes some common failures and how you can fix them. 

Blank Screen - No Output 

Problem: Your system screen is blank and does not show any output. 
Here are possible causes for this problem: 

• Hardware has failed. 

Refer to your system documentation. 

• Keyboard is not attached. 

If the keyboard is not plugged in, the output goes to TTYA instead. To fix 
this problem, power down the system, plug in the keyboard, and power on 
again. 

• Monitor is not turned on or plugged in. 

Check the power cable on the monitor. Make sure the monitor cable is 
plugged into the system frame buffer; then turn the monitor on. 

• output -device is set to TTYA or TTYB. 

This means the NVRAM parameter output-device is set to ttya or ttyb 
instead of being set to screen. You can do one of the following: 

• Power down the system. Then turn it on, and immediately press Stop-N. 
This sets all NVRAM parameters to their default values. As a result, the 
output-device parameter is set to screen. Be warned that all previous 
non-default settings are reset to their default values as well. You must 
restore them as needed. 

• Connect a terminal to TTYA and reset the system. After getting to the ok 
prompt on the terminal, type: screen output to send output to the frame 
buffer. Use setenv to change the default display device, if needed. 

• System has multiple frame buffers. 

If your system has several plugged-in frame buffers, or it has a built-in 
frame buffer and one or more plugged-in frame buffers, then it is possible 
that the wrong frame buffer is being used as the console device. See "Setting 
the Console to a Specific Monitor" on page 112. 
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System Boots From the Wrong Device 

Problem: Your system is supposed to boot from the disk; instead, it boots from 
the net. 

There are two possible causes for this: 

• The diag-switch? NVRAM parameter is inadvertently set to true. 
Interrupt the booting process with Stop-A. Type the following commands 
at the ok prompt: 



ok setenv diag-switch? false 
ok boot 



The system should now start booting from the disk. 

• The boot-device NVRAM parameter is set to net instead of disk. 
Interrupt the booting process with Stop-A. Type the following commands 
at the ok prompt: 



ok setenv boot-device disk 
ok boot 



Note that the preceding commands cause the system to boot from the disk 
defined as disk (target 3) in the device aliases list. If you want to boot from 
diskl (target 1), disk2 (target 2), or disk3 (target 3), set boot-device 
accordingly. 

Problem: Your system is booting from a disk instead of from the net. 

• boot-device is not set to net. 

Interrupt the booting process with Stop-A. Type the following commands 
at the ok prompt: 



ok setenv boot-device net 
ok boot 
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Problem: Your system is booting from the wrong disk. (For example, you have 
more than one disk in your system. You want the system to boot from disk2, 
but the system is booting from diskl instead.) 

• boot- device is not set to the correct disk. 

Interrupt the booting process with Stop-A. Type the following commands 
at the ok prompt: 



ok setenv boot-device disk2 
ok boot 



System Will Not Boot From Ethernet 

Problem: Your system fails to boot from the net. 
The problem could be one of the following: 

• NIS maps are out-of-date. 

Report the problem to your system administrator. 

• Ethernet cable is not plugged in. 

Plug in the ethernet cable. The system should continue with the booting 
process. 

• Server is not responding: no carrier messages. 
Report the problem to your system administrator. 

• tpe-link-test is disabled. 

Refer to the troubleshooting information in your system documentation. 
(Note: systems that do not have Twisted Pair Ethernet will not have the 
tpe-link-test parameter.) 
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System Will Not Boot From Disk 

Problem: You are booting from a disk and the system fails with the message: 

The file just loaded does not appear to be executable. 

• The boot block is missing or corrupted. 
Install a new boot block. 

Problem: You are booting from a disk and the system fails with the message: 

Can't open boot device. 

• The disk may be powered down (especially if it is an external disk). 

Turn on power to the disk, and make sure the SCSI cable is connected to the 
disk and the system. 

SCSI Problems 

Problem: Your system has more than one disk installed, and you get 
SCSI-related errors. 

• Your system might have duplicate SCSI target number settings. 
Try the following procedure: 

a. Unplug all but one of the disks. 

b. At the ok prompt, type: 

ok probe-scsi-all 

Note the target number and its corresponding unit number. 

c. Plug in another disk and perform step b again. 

d. If you get an error, change the target number of this disk to be one of the 
unused target numbers. 

e. Repeat steps b, c, and d until all the disks are plugged back in. 
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Setting the Console to a Specific Monitor 

Problem: You have more than one monitor attached to the system, and the 
console is not set to an intended monitor. 

• If you have more than one monitor attached to the system, the OpenBoot 
firmware always assigns the console to the frame buffer specified by the 
output -device NVRAM parameter. The default value of output -device 
is screen, which is an alias for the first frame buffer that the firmware finds 
in the system. 

A common way to change this default is to change output-device to the 
appropriate frame buffer: 



ok nvalias myscreen /obio/cgfourteen 
ok setenv output-device myscreen 
ok reset 



Another way of setting the console to a specific monitor is to change the 
sbus-probe-list NVRAM parameter. 



ok show sbus-probe-list (Display the current and default values) 

sbus-probe-list f0123 f0123 {Your system may have a different number of SBus slots) 
ok 



If the frame buffer that you are choosing as the console is in slot 2, change 
sbus-probe-list to probe slot 2 first: 



ok setenv sbus-probe-list 23f 01 
ok reset 
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Forth Word Reference 



This appendix contains the Forth commands supported by the OpenBoot 
firmware. 

For the most part, the commands are listed in the order in which they were 
introduced in the chapters. Some of the tables in this appendix show 
commands that are not listed anywhere else in this manual. These additional 
commands (such as memory mapping or output display primitives, or 
machine-specific register commands) are also part of the set of words in the 
OpenBoot implementation of Forth; they are included with relevant groups of 
commands. 
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Table E-l Stack Item Notation 



Notation 


Description 


1 


Alternate stack results, for example: ( input — adr len false 1 result true ). 




Unknown stack items (changed from ???). 


? ? ? 


Unknown stack items. 


acf 


Code field address. 


adr 


Memory address (generally a virtual address). 


adr 1 6 


Memory address, must be 16-bit aligned. 


adr32 


Memory address, must be 32-bit aligned. 


adr64 


Memory address, must be 64-bit aligned. 


byte bxxx 


8-bit value (smallest byte in a 32-bit word). 


char 


7-bit value (smallest byte), high bit unspecified. 


cnt 
len 
size 


Count or length. 


flag xxx? 


0 = false; any other value = true (usually -1). 


long Lxxx 


32-bit value. 


n nl n2 n3 


Normal signed values (32-bit). 


+n u 


Unsigned, positive values (32-bit). 


n [64] 

(n . low n . hi ) 


Extended-precision (64-bit) numbers (2 stack items). 


phys 


Physical address (actual hardware address). 


pstr 


Packed string (adr len means unpacked string). 


virt 


Virtual address (address used by software). 


word wxxx 


16-bit value (smallest two bytes in a 32-bit word). 



Table E-2 Restricted Monitor Commands 


Command 


Description 


b [specifiers] 


Boot the operating system (same as boot at the ok prompt). 


c 


Resume the execution of a halted program (same as go at ok prompt). 


n 


Enter the Forth Monitor. 
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Table E-3 Examining and Creating Device Aliases 



Command 


Description 


devalias 


Display all current device aliases. 


devalias alias 


Display the device path name corresponding to alias. 


devalias alias device-path 


Define an alias representing device-path. 

If an alias with the same name already exists, the new value supercedes the old. 



Table E-4 Commands for Browsing the Device Tree 



Command 


Description 


. attributes 


Display the names and values of the current node's properties. 


cd device-path 


Select the indicated device node, making it the current node. 


cd node-name 


Search for a node with the given name in the subtree below the current node, and select 
the first such node found. 


cd . . 


Select the device node that is the parent of the current node. 


cd / 


Select the root machine node. 


device-end 


De-select the current device node, leaving no node selected. 


Is 


Display the names of the current node's children. 


pwd 


Display the device path name that names the current node. 


show-devs [device-path] 


Display all the devices known to the system directly beneath a given level in the device 
hierarchy, show-devs used by itself shows the entire device tree. 


words 


Display the names of the current node's methods. 


Table E-5 Help Commands 


Command 


Description 


help 


List main help categories. 


help category 


Show help for all commands in the category. Use only the first word of the category 
description. 


help command 


Show help for individual command (where available). 
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Table E-6 Common Options for the boot Command 


Parameter 


Description 


boot [device-specifier] [filename] [options] 


[device-specifier] 


The name (full path name or alias) of the boot device. Typical values include: 

cdrom (CD-ROM drive) 

disk (hard disk) 

floppy (3-1/2" diskette drive) 

net (Ethernet) 

tape (SCSI tape) 


[filename] 


The name of the program to be booted (for example, stand/diag). filename is relative to the root of 
the selected device and partition (if specified). If filename is not specified, the boot program uses the 
value of the boot-file NVRAM parameter (see Chapter 3). 


[options] 


-a - Prompt interactively for the device and name of the boot file, 
-h - Halt after loading the program. 

(These options are specific to the operating system, and may differ from system to system.) 



Table E-7 Diagnostic Test Commands 



Command 


Description 


probe-scsi 


Identify devices attached to the built-in SCSI bus. 


probe-scsi-all [device-path] 


Perform probe-scsi on all SCSI buses installed in the system below the specified 
device tree node. (If device-path is absent, the root node is used.) 


test device-specifier 


Execute the specified device's self-test method. For example: 
test floppy - test the floppy drive, if installed 

test /memory - test number of megabytes specified in the self test-#megs 

NVRAM parameter; or test all of memory if diag-switch? is true 
test net - test the network connection 


test-all [device-specifier] 


Test all devices (that have a built-in self-test method) below the specified device 
tree node. (If device-specifier is absent, the root node is used.) 


watch-clock 


Test the clock function . 


watch-net 


Monitor the network connection. 



116 



OpenBoot Command Reference — August 1994 



Table E-8 System Information Display Commands 



Command 


Description 


banner 


Display power-on banner. 


show-sbus 


Display list of installed and probed SBus devices. 


. enet-addr 


Display current Ethernet address. 


. idprom 


Display ID PROM contents, formatted. 


.traps 


Display a list of SPARC trap types. 


. version 


Display version and date of the boot PROM. 



Table E-9 NVRAM Configuration Parameters 



Parameter 


Typical Default 


Description 


auto-boot ? 


true 


If true, boot automatically after power-on or reset. 


boot-device 


disk 


Device from which to boot. 


boot-file 


empty string 


File to boot (an empty string lets secondary booter choose default). 


boot-f rom 


vmunix 


Boot device and file (1.x only). 


boot-f rom-diag 


le()vmunix 


Diagnostic boot device and file (1.x only). 


diag-device 


net 


Diagnostic boot source device. 


diag-f ile 


empty string 


File from which to boot in diagnostic mode. 


diag-switch? 


false 


If true, run in diagnostic mode. 


f code-debug? 


false 


If true, include name fields for plug-in device FCodes. 


hardware-revision 


no default 


System version information. 


input -device 


keyboard 


Power-on input device (usually keyboard, ttya, or ttyb). 


keyboard- click? 


false 


If true, enable keyboard click. 


keymap 


no default 


Keymap for custom keyboard. 


last -hardware- 
update 


no default 


System update information. 


local-mac-address ? 


false 


If true, network drivers use their own MAC address, not system's. 


mf g-switch? 


false 


If true, repeat system self -tests until interrupted with St op -A. 


nvramrc 


empty 


Contents of NVRAMRC . 


oem-banner 


empty string 


Custom OEM banner (enabled by oem-banner? true). 
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Table E-9 NVRAM Configuration Parameters (Continued) 



Parameter 


Typical Default 


Description 


oem-banner ? 


false 


it true, use custom UhM banner. 


oem-logo 


no default 


Byte array custom OEM logo (enabled by oem-logo? true). 
Displayed in hexadecimal. 


oem- logo ? 


false 


If true, use custom OEM logo (else, use Sun logo). 


output — devi ce 


screen 


Power-on output device (usually screen, ttya, or ttyb). 


sbus — probe - list 


0123 


Which SBus slots are probed and in what order. 


screen— # columns 


80 


Number of on-screen columns (characters /line). 


screen— f rows 


34 


Number of on-screen rows (lines). 


scsi — initiator— id 


7 


SCSI bus address of host adapter, range 0-7. 


sd— target s 


31204567 


Map SCSI disk units (1.x only). 


security— #badlogins 


no default 


Number of incorrect security password attempts. 


secur ity- mode 


none 


Firmware security level (options: none, command, or full). 


security— password 


no default 


Firmware security password (never displayed). Do not set this directly. 


self test-#megs 


1 


Megabytes of RAM to test. Ignored if diag-switch? is true. 


skip-vme-loopback? 


false 


If true, POST does not do VMEbus loopback tests. 


st-targets 


45670123 


Map SCSI tape units (1.x only). 


sunmon-compat ? 


false 


If true, display Restricted Monitor prompt (>). 


testarea 


0 


One-byte scratch field, available for read/write test. 


tpe-link-test ? 


true 


Enable lObaseT link test for built-in twisted pair Ethernet. 


ttya-mode 


9600,8,11,1,- 


TTYA (baud rate, #bits, parity, #stop, handshake). 


ttyb-mode 


9600,8,n,l,- 


TTYB (baud rate, #bits, parity, #stop, handshake). 


ttya-ignore-cd 


true 


If true, operating system ignores carrier-detect on TTYA. 


ttyb-ignore-cd 


true 


If true, operating system ignores carrier-detect on TTYB. 


ttya-rts-dtr-off 


false 


If true, operating system does not assert DTR and RTS on TTYA. 


ttyb-rts-dtr-of f 


false 


If true, operating system does not assert DTR and RTS on TTYB. 


use-nvramrc? 


false 


If true, execute commands in NVRAMRC during system start-up. 


version2 ? 


true 


If true, hybrid (l.x/2.x) PROM comes up in version 2.x. 


wat chdog- reboot ? 


false 


If true, reboot after watchdog reset. 
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Table E-10 Viewing /Changing Configuration Parameters 



Command 


Description 


printenv 


Display all current parameters and current default values. 
(Numbers are usually shown as decimal values.) 

printenv parameter shows the current value of the named parameter. 


setenv parameter value 


Set parameter to the given decimal or text value. 

(Changes are permanent, but usually only take effect after a reset.) 


set-default parameter 


Reset the value of the named parameter to the factory default. 


set-defaults 


Reset parameter values to the factory defaults. 


Table E-ll Configuration Parameter Command Primitives 


Command 


Stack Diagram 


Description 


nodef ault-bytes parameter 


( len - ) 

Usage: ( — adr len ) 


Create custom NVRAM parameter. Use this command in 
NVRAMRC to make the parameter permanent. 


parameter 


( — ??? ) 


Return the (current) field value 
(data type is parameter-dependent). 


show parameter 


(--) 


Display the (current) field value (numbers shown in decimal). 



Table E-12 NVRAMRC Editor Commands 



Command 


Description 


nvalias alias device-path 


Store the command "devalias alias device-path" in NVRAMRC. The alias persists until 
the nvunalias or set-defaults commands are executed. 


nvedit 


Enter the NVRAMRC editor. If data remains in the temporary buffer from a previous 
nvedit session, resume editing those previous contents. If not, read the contents of 
NVRAMRC into the temporary buffer and begin editing it. 


nvquit 


Discard the contents of the temporary buffer, without writing it to NVRAMRC. Prompt 
for confirmation. 


nvrecover 


Recover the contents of NVRAMRC if they have been lost as a result of the execution of 
set-defaults; then enter the editor as with nvedit. nvrecover fails if nvedit is 
executed between the time that the NVRAMRC contents were lost and the time that 

nvrecover is executed. 
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Table E-12 NVRAMRC Editor Commands 


Command 


Description 


nvrun 


Execute the contents of the temporary buffer. 


nvstore 


Copy the contents of the temporary buffer to NVRAMRC; discard the contents of the 
temporary buffer. 


nvunalias alias 


Delete the corresponding alias from NVRAMRC. 



Table E-13 nvedit Keystroke Commands 



Keystroke 


Description 


Control-B 


Move backward one character. 


Control-C 


Exit the NVRAMRC editor and return to the OpenBoot command interpreter. The temporary 
buffer is preserved but is not written back to NVRAMRC. (Use nvstore afterwards to write back 
the temporary buffer.) 


Control-F 


Move forward one character. 


Control-K 


If at the end of a line, join the next line to the current line (that is, delete the new line). 


Control-L 


List all lines. 


Control-N 


Move to the next line of the NVRAMRC editing buffer. 


Control-0 


Insert a new line at the cursor position and stay on the current line. 


Control-P 


Move to the previous line of the NVRAMRC editing buffer. 


Delete 


Delete the previous character. 


Return 


Insert a new line at the cursor position and advance to the next line. 



Table E-14 Stack Manipulation Commands 



Command 


Stack Diagram 


Description 


-rot 


( nl n2 n3 -- n3 nl n2 ) 


Inversely rotate 3 stack items. 


>r 


(n-) 


Move a stack item to the return stack. (Use with caution.) 


?dup 


( n -- n n 1 0 ) 


Duplicate the top stack item if it is non-zero. 


2drop 


( nl n2 - ) 


Remove 2 items from the stack. 


2dup 


( nl n2 -- nl n2 nl n2 ) 


Duplicate 2 stack items. 


2over 


( nl n2 n3 n4 -- nl n2 n3 n4 nl n2 ) 


Copy second 2 stack items. 


2rot 


( nl n2 n3 n4 n5 n6 - n3 n4 n5 n6 nl n2 ) 


Rotate 3 pairs of stack items. 
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Table E-14 Stack Manipulation Commands (Continued) 



Command 


Stack Diagram 


Description 


2 swap 


( nl n2 n3 n4 -- n3 n4 nl n2 ) 


Exchange 2 pairs of stack items. 


3drop 


( nl n2 n3 -- ) 


Remove 3 items from the stack. 


3dup 


( nl n2 n3 -- nl n2 n3 nl n2 n3 ) 


Duplicate 3 stack items. 




( ??? - ) 


Empty the stack. 


depth 


( ??? — ??? +n ) 


Return the number of items on the stack. 


drop 


(n-) 


Remove top item from the stack. 


dup 


( n — n n ) 


Duplicate the top stack item. 


nip 


( nl n2 - n2 ) 


Discard the second stack item. 


over 


( nl n2 - nl n2 nl ) 


Copy second stack item to top of stack. 


pick 


( ??? +n - ??? n2 ) 


Copy +n-th stack item (1 pick = over). 


r> 


(-n) 


Move a return stack item to the stack. (Use with caution.) 


r@ 


(-n) 


Copy the top of the return stack to the stack. 


roll 


( ??? +n - ? ) 


Rotate +n stack items (2 roll = rot). 


rot 


( nl n2 n3 -- n2 n3 nl ) 


Rotate 3 stack items. 


swap 


( nl n2 - n2 nl ) 


Exchange the top 2 stack items. 


tuck 


( nl n2 — n2 nl n2 ) 


Copy top stack item below second item. 



Table E-15 Colon Definition Words 



Command 


Stack Diagram 


Description 


: name 


(--) 


Start creating a new definition. 




(--) 


Finish creating a new definition. 
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Table E-16 Arithmetic Functions 



Command 


Stack Diagram 


Description 




( nl n2 -- n3 ) 


Multiply nl * n2. 


+ 


( nl n2 — n3 ) 


Add nl + n2. 


- 


( nl n2 -- n3 ) 


Subtract nl - n2. 


/ 


( nl n2 — quot ) 


Divide nl / n2; remainder is discarded. 


/mod 


( nl n2 — rem quot ) 


Remainder, quotient of nl / n2. 


<< 


( nl +n - n2 ) 


Left-shift nl by +n bits. 


>> 


( nl +n - n2 ) 


Right-shift nl by +n bits. 


>>a 


( nl +n - n2 ) 


Arithmetic right-shift nl by +n bits. 


*/ 


( nl n2 n3 -- n4 ) 


nl * n2 / n3. 


*/mod 


( nl n2 n3 — rem quot ) 


Remainder, quotient ofnl*n2/n3. 


1 + 


( nl - n2 ) 


Add 1. 


1- 


( nl - n2 ) 


Subtract 1. 


2* 


( nl -- n2 ) 


Multiply by 2. 


2 + 


( nl -- n2 ) 


Add 2. 


2- 


( nl -- n2 ) 


Subtract 2. 


2/ 


( nl -- n2 ) 


Divide by 2. 


abs 


( n — u ) 


Absolute value. 


aligned 


( nl - n2 ) 


Round nl up to the next multiple of 4. 


and 


( nl n2 -- n3 ) 


Bitwise logical AND. 


bounds 


( startadr len — endadr startadr ) 


Convert startadr len to endadr startadr for do loop. 


bl join 


( b.low b2 b3 b.hi — long ) 


Join four bytes to form a 32-bit longword. 


bw join 


( b.low b.hi — word ) 


Join two bytes to form a 16-bit word. 


flip 


( wordl — word2 ) 


Swap the bytes within a 16-bit word. 


Ibsplit 


( long -- b.low b2 b3 b.hi ) 


Split a 32-bit longword into four bytes. 


lwsplit 


( long — w.low w.hi ) 


Split a 32-bit longword into two 16-bit words. 


max 


( nl n2 - n3 ) 


n3 is maximum of nl and n2. 


min 


( nl n2 - n3 ) 


n3 is minimum of nl and n2. 


mod 


( nl n2 — rem ) 


Remainder of nl / n2. 


negate 


( nl - n2 ) 


Change the sign of n 1 . 


not 


( nl - n2 ) 


Bitwise ones complement. 
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Table E-16 Arithmetic Functions (Continued) 



Command 


Stack Diagram 


Description 


or 


( nl n2 - n3 ) 


Bitwise logical OR. 


u*x 


( ul u2 -- product[64] ) 


Multiply 2 unsigned 32-bit numbers; yield unsigned 64-bit 
product. 


u/mod 


( ul u2 — un.rem un.quot ) 


Divide unsigned 32-bit number by an unsigned 32-bit number; 
yield 32-bit remainder and quotient. 


u2/ 


( ul -- u2 ) 


Logical right shift 1 bit; zero shifted into vacated sign bit. 


wbsplit 


( word -- b.low b.hi ) 


Split 16-bit word into two bytes. 


wf lip 


( longl — long2 ) 


Swap halves of 32-bit longword. 


wl join 


( w.low w.hi — long ) 


Join two words to form a longword. 


x+ 


(nl[64] n2[64] -- n3[64] ) 


Add two 64-bit numbers. 


x- 


(nl[64] n2[64] -- n3[64] ) 


Subtract two 64-bit numbers. 


xor 


( nl n2 - n3 ) 


Bitwise exclusive OR. 


xu/mod 


( ul[64] u2 - rem quot ) 


Divide unsigned 64-bit number by unsigned 32-bit number; 
yield 32-bit remainder and quotient. 



Table E-17 Conversion Operators 



Command 


Stack Diagram 


Description 


/c 


(-n) 


The number of bytes in a byte: 1. 


/c* 


( nl - n2 ) 


Multiply nl by / c. 


ca+ 


( adrl index — adr2 ) 


Increment adrl by index times 1 c. 


cal + 


( adrl - adr2 ) 


Increment adrl by /c. 


/L 


(-n) 


Number of bytes in a longword; 4. 


/L* 


( nl - n2 ) 


Multiply nl by /L. 


La+ 


( adrl index — adr2 ) 


Increment adrl by index times /L. 


Lal + 


( adrl -- adr2 ) 


Increment adrl by /L. 


/n 


(-n) 


Number of bytes in a normal; 4. 


/n* 


( nl - n2 ) 


Multiply nl by /n. 


na+ 


( adrl index — adr2 ) 


Increment adrl by index times /n. 


nal + 


( adrl - adr2 ) 


Increment adrl by /n. 


/ w 


(-n) 


Number of bytes in a 16-bit word; 2. 
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Table E-17 Conversion Operators (Continued) 



Command 


Stack Diagram 


Description 


/w* 


( nl - n2 ) 


Multiply nl by /w. 


wa+ 


( adrl index — adr2 ) 


Increment adrl by index times /w. 


wal + 


( adrl -- adr2 ) 


Increment adrl by /w. 



Table E-18 Memory Access Commands 



Command 


Stack Diagram 


Description 


i 


( n adrl6 — ) 


Store a 32-bit number at adr 1 6, must be 16-bit aligned. 


+ ! 


( n adrl6 — ) 


Add n to the 32-bit number stored at adrl 6, must be 16-bit aligned. 


<w@ 


( adrl6 — n ) 


Fetch signed 16-bit word at adrl 6, must be 16-bit aligned. 


? 


( adrl6 -- ) 


Display the 32-bit number at adrl 6, must be 16-bit aligned. 


@ 


( adrl6 — n ) 


Fetch a 32-bit number from adr 1 6, must be 16-bit aligned. 


2 ! 


( nl n2 adrl6 -- ) 


Store 2 numbers at adrl 6, n2 at lower address, must be 16-bit 
aligned. 


2@ 


( adrl6 -- nl n2 ) 


Fetch 2 numbers from adrl 6, n2 from lower address, must be 16-bit 
aligned. 


blank 


( adr u -- ) 


Set u bytes of memory to space (decimal 32). 


c! 


( n adr — ) 


Store low byte of n at adr. 


c? 


( adr — ) 


Display the byte at adr. 


c@ 


( adr — byte ) 


Fetch a byte from adr. 


cmove 


( adrl adr2 u — ) 


Copy u bytes from adrl to adr2, starting at low byte. 


cmove> 


( adrl adr2 u — ) 


Copy u bytes from adrl to adr2, starting at high byte. 


cpeek 


( adr — false 1 byte true ) 


Fetch the byte at adr. Return the data and true if the access was 
successful. Return false if a read access error occurred. 


cpoke 


( byte adr — okay? ) 


Store the byte to adr. Return true if the access was successful. 
Return false if a write access error occurred. 


comp 


( adrl adr2 len — n ) 


Compare two byte arrays, n = 0 if arrays are identical, 
n = 1 if first byte that is different is greater in array#l, 
n = -1 otherwise. 


d! 


( nl n2 adr64 -- ) 


Store two 32-bit numbers at adr 6 4, must be 64-bit aligned. 
Order is implementation-dependent. 


d? 


( adr64 - ) 


Display the two 32-bit numbers at adr64, must be 64-bit aligned. 
Order is implementation-dependent. 
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Table E-18 Memory Access Commands (Continued) 



Command 


Stack Diagram 


Description 


d@ 


( adr64- nl n2 ) 


Fetch two 32-bit numbers from adr 6 4, must be 64-bit aligned. 
Order is implementation-dependent. 


dump 


( adr len — ) 


Display len bytes of memory starting at adr. 


erase 


( adr u -- ) 


Set u bytes of memory to 0. 


fill 


( adr size byte — ) 


Set size bytes of memory to byte. 


L! 


( n adr32 - ) 


Store a 32-bit number at adr32, must be 32-bit aligned. 


L? 


( adr32 - ) 


Display the 32-bit number at adr32, must be 32-bit aligned. 


L@ 


( adr32 - long ) 


Fetch a 32-bit number from adr32, must be 32-bit aligned. 


If lips 


( adr len — ) 


Exchange 16-bit words within 32-bit longwords in specified region. 


lpeek 


( adr32 — false 1 long true ) 


Fetch the 32-bit quantity at adr32. Return the data and true if the 
access was successful. Return false if a read access error occurred. 


lpoke 


( long adr32 — okay? ) 


Store the 32-bit quantity at adr32. Return true if the access was 
successful. Return false if a a write access error occurred. 


move 


( adrl adr2 u — ) 


Copy u bytes from adrl to adr2, handle overlap properly. 


off 


( adrl6 -- ) 


Store false (32-bit 0) at adrl 6. 


on 


( adrl6 -- ) 


Store true (32-bit -1) at adrl 6. 


unaligned-L ! 


( long adr — ) 


Store a 32-bit number, any alignment 


unaligned-L@ 


( adr — long ) 


Fetch a 32-bit number, any alignment. 


unaligned-w ! 


( word adr — ) 


Store a 16-bit number, any alignment. 


unaligned-w@ 


( adr — word ) 


Fetch a 16-bit number, any alignment. 


w! 


( n adrl6 -- ) 


Store a 16-bit number at adr 1 6, must be 16-bit aligned. 


w? 


( adrl6 -- ) 


Display the 16-bit number at adrl 6, must be 16-bit aligned. 


w@ 


( adrl6 — word ) 


Fetch a 16-bit number from adr 1 6, must be 16-bit aligned. 


wf lips 


( adr len — ) 


Exchange bytes within 16-bit words in specified region. 


wpeek 


( adrl6 — false 1 word true ) 


Fetch the 16-bit quantity at adrl6. Return the data and true if the 
access was successful. Return false if a read access error occurred. 


wpoke 


( word adrl6 — okay? ) 


Store the 16-bit quantity to adrl 6. Return true if the access was 
successful. Return false if a write access error occurred. 
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Table E-19 Memory Mapping Commands 



Command 


Stack Diagram 


Description 


alloc-mem 


( size — virt ) 


Allocate and map size bytes of available memory; return the virtual 
address. Unmap with free-mem. 


free-mem 


( virt size -- ) 


Free memory allocated by alloc-mem. 


free-virtual 


( virt size — ) 


Undo mappings created with memmap. 


map? 


( virt -- ) 


Display memory map information for the virtual address. 


memmap 


( phys space size — virt ) 


Map a region of physical addresses; return the allocated virtual 
address. Unmap with free-virtual. 


obio 


( — space ) 


Specify the device address space for mapping. 


obmem 


( — space ) 


Specify the onboard memory address space for mapping. 


sbus 


( — space ) 


Specify the SBus address space for mapping. 



Table E-20 Memory Mapping Primitives 



Command 


Stack Diagram 


Description 


cacheable 


( space — cache-space ) 


Modify the address space so that the subsequent address 
mapping is made cacheable. 


iomap? 


( virt -- ) 


Display IOMMU page map entry for the virtual address. The 
stack diagram shown applies to sun4m machines. 


iomap-page 


( phys space virt — ) 


Map physical page given by phys and space to the virtual 
address. The stack diagram shown applies to sun4m machines. 


iomap-pages 


( phys space virt size — ) 


Perform consecutive iomap-pages to map a region of memory 
given by size. The stack diagram shown applies to sun4m 
machines. 


iopgmapS 


(virt-pte 1 0) 


Return IOMMU page map entry for the virtual address. The stack 
diagram shown applies to sun4m machines. 


iopgmap ! 


( pte virt — ) 


Store a new page map entry for the virtual address. The stack 
diagram shown applies to sun4m machines. 


map-page 


( phys space virt — ) 


Map one page of memory starting at address phys on to virtual 
address virt in the given address space. All addresses are 
truncated to lie on a page boundary. 


map-pages 


( phys space virt size — ) 


Perform consecutive map-pages to map a region of memory to 
the given size. 
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Table E-20 Memory Mapping Primitives (Continued) 



Command 


Stack Diagram 


Description 


map-region 


( region* virt — ) 


Map a region. 


map-regions 


( region# virt size — ) 


Map successive regions. 


map-segments 


( smentry virt len — ) 


Perform consecutive smap ! s to map a region of memory. 


pgmap ! 


( pmentry virt — ) 


Store a new page map entry for the virtual address. 


pgmap? 


( virt — ) 


Display the page map entry (decoded and in English) 
corresponding to the virtual address. 


pgmap @ 


( virt — pmentry ) 


Return the page map entry for the virtual address. 


pagesize 


( — size ) 


Return the size of a page, often 4K (hex 1000). 


rmap ! 


( rmentry virt — ) 


Store a new region map entry for the virtual address. 


rmapd 


( virt — rmentry ) 


Return the region map entry for the virtual address. 


segmentsize 


( — size ) 


Return the size of a segment, often 256K (hex 40000). 


smap ! 


( smentry virt — ) 


Store a new segment map entry for the virtual address. 


smap? 


( virt — ) 


Formatted display of the segment map entry for the virtual 
address. 


smap@ 


( virt — smentry ) 


Return the segment map entry for the virtual address. 



Table E-21 Cache Manipulation Commands 



Command 


Stack Diagram 


Description 


clear-cache 


(") 


Invalidate all cache entries. 


cache-off 


(") 


Disable the cache. 


cache-on 


(") 


Enable the cache. 


cdata ! 


( data offset — ) 


Store the 32-bit data at the cache offset. 


cdata@ 


( offset — data ) 


Fetch (return) data from the cache offset. 


ctag ! 


( value offset — ) 


Store the tag value at the cache offset. 


ctag@ 


( offset — value ) 


Return the tag value at the cache offset. 


flush-cache 


(--) 


Write back any pending data from the cache. 
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Table £-22 Reading/Writing Machine Registers in Sun-4D Machines 



Command 


Stack Diagram 


Description 


SuperSPARC™ Module Register Access 


cxr ! 


( data -- ) 


Write MMU context register. 


mcr ! 


( data -- ) 


Write module control register. 


cxr@ 


( -- data ) 


Read MMU context register. 


mcr@ 


( -- data ) 


Read MMU control register. 


sf sr@ 


( -- data ) 


Read synchronous fault status register. 


sfard 


( -- data ) 


Read synchronous fault address register. 


af sr@ 


( -- data ) 


Read asynchronous fault status register. 


afard 


( -- data ) 


Read asynchronous fault address register. 


. mcr 


(--) 


Display module control register. 


. sf sr 


(--) 


Display synchronous fault status register. 


MXCC Interrupt Register Access 


interrupt-enable ! 


( data -- ) 


Write interrupt mask register. 


inter rupt-enable@ 


( -- data ) 


Read interrupt mask register. 


inter rupt-pending@ 


( -- data ) 


Read interrupt pending register. 


interrupt-clear ! 


( data -- ) 


Write interrupt clear register. 


BootBus Register Access 


control ! 


( datat -- ) 


Write BootBus control register. 


control@ 


( -- datat ) 


Read BootBus control register. 


statusl@ 


( -- datat ) 


Read BootBus statusl register. 


status2@ 


( -- datat ) 


Read BootBus status2 register. 
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Table £-23 Reading/Writing Machine Registers in Sun-4M Machines 



Command 


Stack Diagram 


Description 


. mcr 


(--) 


Display module control register. 


.mfsr 


(--) 


Display memory controller fault status register. 


. sf sr 


(--) 


Display synchronous fault status register. 


. sipr 


(--) 


Display system interrupt pending register. 


aux ! 


( data — ) 


Write auxiliary register. 


aux@ 


( — data ) 


Read auxiliary register. 


cxr ! 


( data — ) 


Write MMU context register. 


cxr@ 


( — data ) 


Read MMU context register. 


interrupt-enable ! 


( data — ) 


Write system interrupt target mask register. 


inter rupt -enable @ 


( — data ) 


Read system interrupt target mask register. 


iommu-ctl ! 


( data — ) 


Write IOMMU control register. 


iommu-ctl@ 


( -- data) 


Read IOMMU control register. 


mcr ! 


( data — ) 


Write module control register. 


mcr@ 


( — data ) 


Read module control register. 


mfsr ! 


( data — ) 


Write memory controller fault status register. 


mf sr@ 


( — data ) 


Read memory controller fault status register. 


msaf ar@ 


( — data ) 


Read MBus-to-SBus asynchronous fault address register. 


msaf sr ! 


( data — ) 


Write MBus-to-SBus asynchronous fault status register. 


msaf sr@ 


( — data ) 


Read MBus-to-SBus asynchronous fault status register. 


sf sr ! 


( data — ) 


Write synchronous fault status register. 


sf sr@ 


( — data ) 


Read synchronous fault status register. 


sfar ! 


( data — ) 


Write synchronous fault address register. 


sfar@ 


( — data ) 


Read synchronous fault address register. 
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Table £-24 Reading/Writing Machine Registers in Sun-4C Machines 



Command 


Stack Diagram 


Description 


aerr ! 


( data — ) 


Write asynchronous error register. 


aerr@ 


( — data ) 


Read asynchronous error register. 


averr ! 


( data — ) 


Write asynchronous error virtual address register. 


averrg 


( — data ) 


Read asynchronous error virtual address register. 


aux ! 


( data — ) 


Write auxiliary register. 


aux@ 


( — data ) 


Read auxiliary register. 


context ! 


( data — ) 


Write context register. 


contexts 


( — data ) 


Read context register (MMU context). 


dcontext @ 


( — data ) 


Read context register (cache context). 


enable ! 


( data — ) 


Write system enable register. 


enableg 


( — data ) 


Read system enable register. 


interrupt- 
enable ! 


( data -- ) 


Write interrupt enable register. 


interrupt- 
enable@ 


( — data ) 


Read interrupt enable register. 


serr ! 


( data -- ) 


Write synchronous error register. 


serr@ 


( — data ) 


Read synchronous error register. 


sverr ! 


( data — ) 


Write synchronous error virtual address register. 


sverrg 


( — data ) 


Read synchronous error virtual address register. 



130 



OpenBoot Command Reference — August 1994 



Table £-25 Alternate Address Space Access Commands 



Command 


Stack Diagram 


Description 


spacec ! 


( byte adr asi — ) 


Store the byte at asi and address. 


spacec? 


( adr asi — ) 


Display the byte at asi and address. 


spaced? 


( adr asi — byte ) 


Fetch the byte from asi and address. 


spaced ! 


( nl n2 adr asi -- ) 


Store the two 32-bit words at asi and address. 
Order is implementation-dependent. 


spaced? 


( adr asi — ) 


Display the two 32-bit words at asi and address. 
Order is implementation-dependent. 


spacedS 


( adr asi — nl n2 ) 


Fetch the two 32-bit words from asi and address. 
Order is implementation-dependent. 


spaceL ! 


( long adr asi — ) 


Store the 32-bit word at asi and address. 


spaceL? 


( adr asi — ) 


Display the 32-bit word at asi and address. 


spaceLS 


( adr asi — long ) 


Fetch the 32-bit word from asi and address. 


spacew ! 


( word adr asi — ) 


Store the 16-bit word at asi and address. 


spacew? 


( adr asi — ) 


Display the 16-bit word at asi and address. 


spacewO 


( adr asi — word ) 


Fetch the 16-bit word from asi and address. 



Table £-26 Defining Words 



Command 


Stack Diagram 


Description 


: name 


(") 

Usage: ( 111 - ? ) 


Start creating a new colon definition. 




(") 


Finish creating a new colon definition. 


alias new-name old-name 


(") 

Usage: ( 111 - 1 ) 


Create new-name with the same behavior as old-name. 


buffer: name 


( size — ) 

Usage: ( — adr64 ) 


Create a named array in temporary storage. 


constant name 


(n-) 

Usage: ( -- n ) 


Define a constant (for example, 3 constant bar). 


2constant name 


( nl n2 - ) 
Usage: ( -- nl n2 ) 


Define a 2-number constant. 
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Table £-26 Defining Words (Continued) 



Command 


Stack Diagram 


Description 


create name 


(") 

Usage: ( -- adrl6 ) 


Generic defining word. 


defer name 


(") 

Usage: ( ??? - ? ) 


Define a word for forward references or execution vectors 
using code field address. 


does> 


( - adrl6 ) 


Start the run-time clause for defining words. 


field name 


( offset size — offset+size ) 
Usage: ( adr — adr+offset ) 


Create a named offset pointer. 


struct 


(-0) 


Initialize for field creation. 


value name 


(n-) 

Usage: ( — n ) 


Create a changeable, named 32-bit quantity. 


variable name 


(") 

Usage: ( -- adr!6 ) 


Define a variable. 



Table £-27 Dictionary Searching Commands 



Command 


Stack Diagram 


Description 


' name 


( " acf ) 


Find the named word in the dictionary. 

Returns the code field address. Use outside definitions. 


[ ' ] name 


( " acf ) 


Similar to ' but is used either inside or outside definitions. 


. calls 


( acf - ) 


Display a list of all words that call the word whose 
compilation address is acf. 


$f ind 


( adr len — adr len false 1 acf n ) 


Find a word, n = 0 if not found, n = 1 if immediate, 
n = -1 otherwise. 


find 


( pstr — pstr false 1 acf n ) 


Search for a word in the dictionary. The word to be found is 
indicated by pstr. n = 0 if not found, n = 1 if immediate, 
n = -1 otherwise. 


see thisword 


(") 


Decompile the named command. 


( see ) 


(acf-) 


Decompile the word indicated by the code field address. 


sift 


( pstr - ) 


Display names of all dictionary entries containing the string 
pointed to by pstr. 


sifting ccc 


(") 


Display names of all dictionary entries containing the 
sequence of characters, ccc contains no spaces. 


words 


(") 


Display all visible words in the dictionary. 
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Table E-28 Dictionary Compilation Commands 



Command 


Stack Diagram 


Description 


r 


( n - ) 


Place a number in the dictionary. 


c, 


( byte — ) 


Place a byte in the dictionary. 


w, 


( word — ) 


Place a 16-bit number in the dictionary. 


L, 


( long - ) 


Place a 32-bit number in the dictionary. 


[ 


(--) 


Begin interpreting. 


] 


(--) 


End interpreting, resume compilation. 


allot 


(n-) 


Allocate n bytes in the dictionary. 


>body 


( acf — apf ) 


Find parameter field address from compilation 
address. 


body> 


( apf — acf ) 


Find compilation address from parameter field 
address. 


compile 


(--) 


Compile next word at run time. 


[compile] name 


(--) 


Compile the next (immediate) word. 


forget name 


(--) 


Remove word from dictionary and all subsequent 
words. 


here 


( - adr ) 


Address of top of dictionary. 


immediate 


(--) 


Mark the last definition as immediate. 


is name 


(n-) 


Install a new action in a defer word or value. 


literal 


(n-) 


Compile a number. 


origin 


( — adr ) 


Return the address of the start of the Forth system. 


patch new-word old-word word-to-patch 


(--) 


Replace old-word with new-word in word-to-patch. 


(patch 


( new-n old-n acf — ) 


Replace old-n with new-n in word indicated 
by acf. 


recursive 


(--) 


Make the name of the colon definition being 
compiled visible in the dictionary, and thus allow 
the name of the word to be used recursively in its 
own definition. 


state 


( - adr ) 


Variable that is non-zero in compile state. 
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Table E-29 Assembly Language Programming 



Command 


Stack Diagram 


Description 


code name 


(--) 

Usage: ( ??? -- ? ) 


Begin the creation of an assembly language routine called name. Commands that 
follow are interpreted as assembler mnemonics. Note that if the assembler is not 
installed, code is still present, except that machine code must be entered 
numerically (for example, in hex) with 


c; 


(--) 


End the creation of an assembly language routine. Automatically assemble the 
Forth interpreter "next" function so that the created assembly-code word, when 
executed, returns control to the calling routine as usual. 


label name 


(--) 

Usage: ( -- adrl6 ) 


Begin the creation of an assembly language routine called name. Words created 
with label leave the address of the code on the stack when executed. The 
commands that follow are interpreted as assembler mnemonics. As with code, 
label is present even if the assembler is not installed. 


end-code 


(--) 


End the assembly language patch started with label. 



Table E-30 Basic Number Display 



Command 


Stack Diagram 


Description 




(n-) 


Display a number in the current base. 


. r 


( n size — ) 


Display a number in a fixed width field. 


. s 


(--) 


Display contents of data stack. 


showstack 


(--) 


Execute . s automatically before each ok prompt. 


u . 


(U-) 


Display an unsigned number. 


u . r 


( u size — ) 


Display an unsigned number in a fixed width field. 
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Table E-31 Changing the Number Base 



Command 


Stack Diagram 


Description 


base 


( — adr ) 


Variable containing number base. 


binary 


(--) 


Set the number base to 2. 


decimal 


(--) 


Set the number base to 10. 


d# number 


(-n) 


Interpret the next number in decimal; base is unchanged. 


hex 


(--) 


Set the number base to 16. 


h# number 


(-n) 


Interpret the next number in hex; base is unchanged. 


.d 


(n-) 


Display n in decimal without changing base. 


.h 


(n-) 


Display n in hex without changing base. 



Table E-32 Numeric Output Word Primitives 



Command 


Stack Diagram 


Description 


# 


( +L1 - +L2 ) 


Convert a digit in pictured numeric output. 


#> 


( L - adr +n ) 


End pictured numeric output. 


<# 


(") 


Initialize pictured numeric output. 


( - ) 


(n-) 


Convert a number to a string. 


(u.) 


( — adr len ) 


Convert unsigned to string. 


digit 


( char base — digit true 1 char false ) 


Convert a character to a digit. 


hold 


( char — ) 


Insert the char in the pictured numeric output string. 


$ number 


( adr len — true 1 n false ) 


Convert a string to a number. 


#s 


( L - 0 ) 


Convert the rest of the digits in pictured numeric output. 


sign 


(n-) 


Set sign of pictured output. 
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Table E-33 Controlling Text Input 



Command 


Stack Diagram 


Description 


( ccc ) 


(") 


Begin a comment. 


\ rest-of-line 


(") 


Skip the rest of the line. 


ascii ccc 


( — char ) 


Get numerical value of first ASCII character of next word. 


expect 


( adr +n — ) 


Get a line of edited input from the assigned input device's 
keyboard; store at adr. 


key 


( — char ) 


Read a character from the assigned input device's keyboard. 


key? 


( " flag ) 


True if a key has been typed on the input device's keyboard. 


span 


( - adrl6 ) 


Variable containing the number of characters read by expect. 


word 


( char — pstr ) 


Collect a string delimited by char from input string and place 
in memory at pstr. 



Table E-34 Displaying Text Output 



Command 


Stack Diagram 


Description 


. " ccc" 


(--) 


Compile a string for later display. 


(cr 


(--) 


Move the output cursor back to the beginning of the current line. 


cr 


(--) 


Terminate a line on the display and go to the next line. 


emit 


( char — ) 


Display the character. 


exit? 


( " flag ) 


Enable the scrolling control prompt: More [<space>,<cr>,q] ? 
The return flag is true if the user wants the output to be terminated. 


space 


(") 


Display a space character. 


spaces 


( +n - ) 


Display +n spaces. 


type 


( adr +n — ) 


Display n characters. 


Table E-35 Formatted Output 


Command 


Stack Diagram 


Description 


#line 


( - adrl6 ) 


Variable holding the line number on the output device. 


tout 


( - adr!6 ) 


Variable holding the column number on the output device. 
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Table E-36 Manipulating Text Strings 



Command 


Stack Diagram 


Description 




( adr len — ) 


Compile an array of bytes from adr of length len, 
at the top of the dictionary as a packed string. 


" ccc " 


( — adr len ) 


Collect an input stream string, either interpreted or 
compiled. Within the string, " ( 0 0 , f f . . . ) can be 
used to include arbitrary byte values. 


. ( ccc) 


(") 


Display a string immediately. 


-trailing 


( adr +nl - adr +n2 ) 


Remove trailing spaces. 


bl 


( — char ) 


ASCII code for the space character; decimal 32. 


count 


( pstr — adr +n ) 


Unpack a packed string. 


lcc 


( char — lowercase-char ) 


Convert a character to lowercase. 


left -parse-string 


( adr len char — adrR lenR adrL lenL ) 


Split a string at the given delimiter (which is 
discarded). 


pack 


( adr len pstr — pstr ) 


Make a packed string from adr len; place it at 
pstr. 


p" ccc" 


( " pstr ) 


Collect a string from the input stream; store as a 
packed string. 


upc 


( char — uppercase-char ) 


Convert a character to uppercase. 



Table E-37 I/O Redirection Commands 



Command 


Stack Diagram 


Description 


input 


( device — ) 


Select device (ttya, ttyb, keyboard, or " device-specifier") for 
subsequent input. 


io 


( device — ) 


Select device for subsequent input and output. 


output 


( device — ) 


Select device (ttya, ttyb, screen, or " device-specifier") for 
subsequent output. 
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Table E-38 ASCII Constants 



Command 


Stack Diagram 


Description 


bell 


(-n) 


ASCII code for the bell character; decimal 7. 


bs 


(-n) 


ASCII code for the backspace character; decimal 8. 



Table E-39 Line Editor Commands 



Command 


Function 


Control-A 


Go to start of line. 


Control-B 


Go backward one character. 


Control-D 


Erase this character. 


Control-E 


Go to end of line. 


Control-F 


Go forward one character. 


Control-H 


Erase previous character (also Delete or Back Space keys). 


Control-K 


Erase forward, from here to end of line. 


Control-L 


Show command history list, then re-type line. 


Control-N 


Recall subsequent command line. 


Control-P 


Recall previous command line. 


Control-Q 


Quote next character (to type a control character). 


Control-R 


Re-type line. 


Control-U 


Erase entire line. 


Control-W 


Erase previous word. 


Control-Y 


Insert save buffer contents before the cursor. 


Control-space 


Complete the current command. 


Control-/ 


Show all possible matches /completions. 


Control-? 


Show all possible matches /completions. 


Control- } 


Show all possible matches /completions. 


Esc-B 


Go backward one word. 


Esc-D 


Erase this portion of word, from here to end of word. 


Esc-F 


Go forward one word. 


Esc-H 


Erase previous portion of word (also Control-w). 
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Table E-40 Comparison Commands 



Command 


Stack Diagram 


Description 


< 


( nl n2 -- flag ) 


True if nl < n2. 


<= 


( nl n2 -- flag ) 


True if nl <= n2. 


<> 


( nl n2 -- flag ) 


True if nl <> n2. 




( nl n2 -- flag ) 


True if nl = n2. 


> 


( nl n2 -- flag ) 


True if nl > n2. 


>= 


( nl n2 -- flag ) 


True if nl >= n2. 


0< 


( n -- flag ) 


True if n < 0. 


0<= 


( n -- flag ) 


True if n <= 0. 


0<> 


( n -- flag ) 


True if n <> 0. 


0 = 


( n -- flag ) 


True if n = 0 (also inverts any flag). 


0> 


( n -- flag ) 


True if n > 0. 


0>= 


( n -- flag ) 


True if n >= 0. 


between 


( n min max — flag ) 


True if min <= n <= max. 


false 


(-0) 


The value FALSE, which is 0. 


true 


( - -1 ) 


The value TRUE, which is -1. 


u< 


( ul u2 -- flag ) 


True if ul < u2, unsigned. 


u<= 


( ul u2 -- flag ) 


True if ul <= u2, unsigned. 


u> 


( ul u2 -- flag ) 


True if ul > u2, unsigned. 


u>= 


( ul u2 -- flag ) 


True if ul >= u2, unsigned. 


within 


( n min max — flag ) 


True if min <= n < max. 
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Table E-41 if-then-else Commands 



Command 


Stack Diagram 


Description 


else 


(") 


Execute the following code if if failed. 


if 


( flag - ) 


Execute following code if flag is true. 


then 


(--) 


Terminate if. . .then. . .else. 



Table E-42 case Statement Commands 



Command 


Stack Diagram 


Description 


case 


( selector — selector ) 


Begin a case . . . endcase conditional. 


endcase 


( selector 1 (empty) — ) 


Terminate a case . . . endcase conditional. 


endof 


(--) 


Terminate an of . . .endof clause within a 
case . . . endcase 


of 


( selector test-value — selector 1 {empty} ) 


Begin an of . . . endof clause within a case conditional. 



Table E-43 begin (Conditional) Loop Commands 



Command 


Stack Diagram 


Description 


again 


(") 


End a begin . . . again infinite loop. 


begin 


(--) 


Begin a begin . . . while . . . repeat, begin . . . until , or 
begin. . .again loop. 


repeat 


(--) 


End a begin . . . while . . . repeat loop. 


until 


( flag - ) 


Continue executing a begin . . . until loop until flag is true. 


while 


( flag - ) 


Continue executing a begin . . . while . . . repeat loop while 
flag is true. 
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Table E-44 do (Counted) Loop Commands 



Command 


Stack Diagram 


Description 


+ loop 


(n-) 


End a do . . . +loop construct; add n to loop index and return to do (if n 
< 0, index goes from start to end inclusive). 


?do 


( end start — ) 


Begin ?do . . . loop to be executed 0 or more times. Index goes from 
start to end-1 inclusive. If end = start, loop is not executed. 


?leave 


( flag -- ) 


Exit from a do . . . loop if flag is non-zero. 


do 


( end start — ) 


Begin a do . . . loop. Index goes from start to end-1 inclusive. 
Example: 10 0 do i . loop (prints 0 1 2.. .d e f). 


i 


(-n) 


Loop index. 


j 


(-n) 


Loop index for next enclosing loop. 


leave 


(--) 


Exit from do . . . loop . 


loop 


(--) 


End of do . . . loop . 



Table E-45 Program Execution Control Commands 



Command 


Stack Diagram 


Description 


abort 


(--) 


Abort current execution and interpret keyboard commands. 


abort" ccc" 


( abort? - ) 


If flag is true, abort and display message. 


eval 


( adr len — ) 


Interpret Forth source from an array. 


execute 


(acf-) 


Execute the word whose code field address is on the stack. 


exit 


(--) 


Return from the current word. (Cannot be used in counted loops.) 


quit 


(--) 


Same as abort, but leave stack intact. 
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Table E-46 File Loading Commands 



Command 


Stack Diagram 


Description 


?go 


(") 


Execute Forth, FCode, or binary programs. 


boot [specifiers] -h 


(") 


Load file from specified source. 


byte-load 


( adr span — ) 


Interpret loaded FCode binary file, span is usually 1. 


dl 


(") 


Load a Forth file over a serial line with TIP and interpret. Type: 

~C cat filename 

A -D 


dlbin 


(") 


Load a binary file over a serial line with TIP. 
Type: ~C cat filename 


dload filename 


( adr - ) 


Load the specified file over Ethernet at the given address. 


eval 


( adr len — ) 


Interpret loaded Forth text file. 


go 


(--) 


Begin executing a previously-loaded binary program, or resume 
executing an interrupted program. 


init-program 


(--) 


Initialize to execute a binary file. 


load device-specifier argument 


(--) 


Load data from specified device into memory at the address given 

by load-base. 


load-base 


( - adr ) 


Address at which load places the data it reads from a device. 


Table E-47 Disassembler Commands 


Command 


Stack Diagram 


Description 


+ dis 


(") 


Continue disassembling where the last disassembly left off. 


dis 


( adr - ) 


Begin disassembling at the given address. 
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Table E-48 SPARC Register Commands 



Command 


Stack Diagram 


Description 


%f0 through %f31 


( — value ) 


Return the value in the given floating point register. 


%fsr 


( — value ) 


Return the value in the given floating point register. 


%g0 through %g7 


( — value ) 


Return the value in the given register. 


%i0 through %i7 


( — value ) 


Return the value in the given register. 


%L0 through %L7 


( — value ) 


Return the value in the given register. 


%o0 through %o7 


( — value ) 


Return the value in the given register. 


%pc %npc %psr 


( — value ) 


Return the value in the given register. 


%y %wim %tbr 


( — value ) 


Return the value in the given register. 


. f registers 


(") 


Display values in %f 0 through %f 31 . 


. locals 


(") 


Display the values in the i, L and o registers. 


.psr 


(") 


Formatted display of the %psr data. 


. registers 


(") 


Display values in %g0 through %g7, plus %pc, %npc, %psr, %y, %wim, %tbr . 


. window 


( window* — ) 


Same as w . locals; display the desired window. 


ctrace 


(") 


Display the return stack showing C subroutines. 


set-pc 


( value — ) 


Set %pc to the given value, and set %npc to (value+4). 


to regname 


( value — ) 


Change the value stored in any of the above registers. 
Use in the form: value to regname. 


W 


( window* — ) 


Set the current window for displaying %ix, %Lx, or %ox. 
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Table E-49 Breakpoint Commands 



Command 


Stack Diagram 


Description 


+bp 


( adr - ) 


Add a breakpoint at the given address. 


-bp 


( adr - ) 


Remove the breakpoint at the given address. 


—bp 


(--) 


Remove the most-recently-set breakpoint. 


.bp 


(--) 


Display all currently set breakpoints. 


. breakpoint 


(--) 


Perform a specified action when a breakpoint occurs. This word can be altered to 
perform any desired action. For example, to display registers at every breakpoint, 
type: ['] .registers is . breakpoint. The default behavior is 
. instruction. To perform multiple behaviors, create a single definition which 
calls all desired behaviors, then load that word into .breakpoint. 


. instruction 


(--) 


Display the address, opcode for the last-encountered breakpoint. 


. step 


(--) 


Perform a specified action when a single step occurs (see .breakpoint). 


bpoff 


(--) 


Remove all breakpoints. 


finish-loop 


(--) 


Execute until the end of this loop. 


go 


(--) 


Continue from a breakpoint. This can be used to go to an arbitrary address by 
setting up the processor's program counter before issuing go. 


gos 


(n-) 


Execute go n times. 


hop 


(--) 


(Like the step command.) Treat a subroutine call as a single instruction. 


hops 


(n-) 


Execute hop n times. 


return 


(") 


Execute until the end of this subroutine. 


returnL 


(") 


Execute until the end of this leaf subroutine. 


skip 


(") 


Skip (do not execute) the current instruction. 


step 


(") 


Single-step one instruction. 


steps 


(n-) 


Execute step n times. 


till 


( adr — ) 


Execute until the given address is encountered. Equivalent to +bp go . 
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Table E-50 Forth Source-level Debugger Commands 


Command 


Description 


C 


"Continue". Switch from stepping to tracing, thus tracing the remainder of the execution of the word 
being debugged. 


D 


"Down a level". Mark for debugging the word whose name was just displayed, then execute it. 


F 


Start a subordinate Forth interpreter. When that interpreter exits (with resume), control returns to the 
debugger at the place where the F command was executed. 


Q 


"Quit". Abort the execution of the word being debugged and all its callers and return to the command 
interpreter. 


u 


"Up a level". Un-mark the word being debugged, mark its caller for debugging, and finish executing 
the word that was previously being debugged. 


debug name 


Mark the named Forth word for debugging. Enter the Forth Source-level Debugger with any 
subsequent attempts to execute that word. After executing debug, the execution speed of the system 
may decrease until debugging is turned off with debug-off. (Do not debug basic Forth words such 
as ".".) 


debug-off 


Turn off the Forth Source-level Debugger so that no word is being debugged. 


resume 


Exit from a subordinate interpreter, and go back to the stepper (see the F command in this table). 


stepping 


Set "step mode" for the Forth Source-level Debugger, allowing the interactive, step-by-step execution 
of the word being debugged. Step mode is the default. 


tracing 


Set "trace mode" for the Forth Source-level Debugger. This traces the execution of the word being 
debugged, while showing the name and stack contents for each word called by that word. 


Space 


Execute the word just displayed and proceed to the next word. 



Table E-51 Time Utilities 



Command 


Stack Diagram 


Description 


get-msecs 


( - ms ) 


Return the approximate current time in milliseconds. 


ms 


(n-) 


Delay for n milliseconds. Resolution is 1 millisecond. 
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Table E-52 Miscellaneous Operations 



Command 


Stack Diagram 


Description 


callback string 


( value — ) 


Call SunOS with the given value and string. 


catch 


( ??? acf — ? error-code ) 


Execute acf; return throw error code or 0 if throw is not called. 


e ject-f loppy 


(") 


Eject the diskette from the floppy drive. 


firmware -version 


(-- n) 


Return major/minor CPU firmware version 
(that is, 0x00020001 = firmware version 2.1). 


forth 


(--) 


Restore main Forth vocabulary to top of search order. 


f trace 


(--) 


Show calling sequence when exception occurred. 


noop 


(--) 


Do nothing. 


old-mode 


(--) 


Go to Restricted Monitor. 


reset 


(--) 


Reset the entire system (similar to a power-cycle). 


ramf orth 


(--) 


Copy Forth dictionary to RAM. (Speeds up interpretation in 
some systems and enables system word patching.) 


romf orth 


(--) 


Turn off ramf orth. 


sync 


(--) 


Call the operating system to write any pending information to 
the hard disk. Also boot after sync-ing file systems. 


throw 


( error-code — ) 


Return given error code to catch. 


Table E-53 Multiprocessor Commands 


Command 


Stack Diagram 


Description 


module-info 


(") 


Display type and speed of all CPU modules. 


switch-cpu 


( cpu# - ) 


Switch to indicated CPU. 
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Table E-54 Emergency Keyboard Commands 



Command 


Description 


Stop 


Bypass POST. This command does not depend on security-mode. (Note: some systems bypass 
POST as a default; in such cases, use Stop-D to start POST.) 


Stop-A 


Abort. 


Stop-D 


Enter diagnostic mode (set diag-switch? to true). 


Stop-F 


Enter Forth on TTYA instead of probing. Use f exit to continue with the initialization sequence. 
Useful if hardware is broken. 


Stop-N 


Reset NVRAM contents to default values. 
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! 55, 62, 124 
"ccc" 68,137 
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# 135 
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#out 136 
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%f0 88, 143 
%fsr 88, 143 
%g0 88, 143 
%i0 88, 143 
%L0 88,143 
%npc 88, 89, 143 
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(.) 135 
(cr 136 
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(patch 64, 133 
(see) 63,132 
(u.) 135 
) 52,67 
* 52, 122 
V 52,122 
*/mod 52, 122 
+ 47, 52, 122 
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+bp 89, 90, 144 
+dis 87, 142 
+loop 78,141 
+n 49, 114 
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. 47,65,134 
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.h 62, 65, 66, 135 
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.locals 88, 143 
.mcr 129 
.mfsr 129 
.psr 88, 143 
.r 65, 134 
.registers 88, 143 
.s 65, 134 
.sfsr 129 
.sipr 129 
.step 90,144 
.traps 21, 117 
.version 21, 117 
.window 88, 89, 143 
/ 52,122 
/c 123 
/c* 123 

/ etc /remote file 94 
/L 123 
/L* 123 
/mod 52, 122 
/n 123 
/n* 123 
/w 123 
/w* 124 

: 50, 51, 60, 121, 131 
; 50, 51, 60, 121, 131 
< 73, 139 
<# 135 
« 52, 122 
<= 73,139 
<> 73,139 
<w@ 55, 124 
= 73,139 

> 73,74,139 

> = 73, 139 
» 52, 122 



»a 52, 122 

>body 64, 133 

>r 49, 120 

? 48, 55, 114, 124 

??? 48, 114 

?do 78, 141 

?dup 49, 120 

?go 81, 142 

?leave 78, 141 

@ 54, 55, 61, 62, 124 

[ 64, 133 

['] 63,132 

[compile] 64,133 

\ 66,67,136 

] 64,133 

I 48,114 

~. 95 

" 101 

' 62, 63, 132 

Numerics 

0< 73, 139 
0<= 73, 139 
0<> 73, 139 
0= 73, 74, 139 
0> 73, 139 
0>= 73, 139 

1- 52, 122 
1+ 52, 122 

2- 52, 122 
2! 55,124 
2* 52, 122 
2+ 52, 122 
2/ 52,122 
2@ 55, 124 
2constant 60, 131 
2drop 49, 120 
2dup 49, 120 
2over 49, 120 
2rot 49, 120 



OpenBoot Command Reference 



-—August 1994 



2swap 49, 121 
3drop 49, 121 
3dup 49, 121 
n 49, 114 

A 

abort 80, 141 

abort" 80,141 

abs 53, 122 

acf 48, 114 

adr 48, 114 

adrl6 48, 114 

adr32 48, 114 

adr64 48, 114 

aerr! 130 

aerr@ 130 

again 77, 140 

alias 60,131 

aligned 53, 122 

alloc-mem 57, 101, 126 

allot 64, 133 

alternate address space commands 131 
and 53, 122 

arithmetic functions 52, 122 

ascii 66, 67, 136 

ASCII constants 138 

assembly language commands 134 

auto-boot? 24, 36, 117 

aux! 129,130 

aux@ 129,130 

averr! 130 

averr® 130 

B 

b (boot) 30, 31 
banner 21, 32, 38, 117 
base 65, 135 
baud rate 25, 35 
begin 77, 140 



begin loops 77 
bell 138 
between 73, 139 
binary 65, 135 

binary executable programs 83, 84, 85 

bl 68, 137 

blank 55, 124 

bljoin 53, 122 

body> 64,133 

boot 38, 81, 142 

boot command options 14, 116 

boot-h 90 

boot-device 24, 36, 101, 117 
boot-file 24, 36, 101, 117 
boot-from 24, 117 
boot-from-diag 24, 117 
booting failures 108 to 112 
bounds 53, 122 
-bp 89, 144 
--bp 89,144 
bpoff 90, 144 

breakpoint commands 89, 144 
bs 138 

buffer: 60, 131 

building bootable floppy disks 97 
bwjoin 53, 122 
byte 48 
byteb 114 
byte-load 81,142 

c 

c (continue) 30, 31 
c! 55,57,124 
c, 64, 133 
c; 134 
c? 55, 124 
c@ 55, 78, 124 
ca+ 123 
cal+ 123 

cache manipulation commands 127 
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cacheable 126 
cache-off 127 
cache-on 127 
call opcode 87 
callback 146 
carriage-return 68 
case 76, 140 
catch 146 
cd 8, 101, 115 
cdata! 127 
cdata® 127 

changing the number base 65, 135 

char 48, 114 

clear 49, 121 

clear_colormap 21 

clear-cache 127 

cmove 55, 124 

cmove> 55, 124 

cnt 48, 114 

code 134 

code field address 60, 63 
colon definitions 50 
command completion 72, 101 
command security mode 30 
comments in Forth code 67 
comp 55, 124 

comparison commands 73, 139 
compile 64, 133 

compiling data into the dictionary 64, 133 
configuration parameter primitives 119 
configuration parameters 

displaying 26 

resetting to defaults 26 

setting 26, 28 
constant 60, 61, 131 
context! 130 
context® 130 
conversion operators 123 
count 68, 69, 137 
cpeek 55, 101, 124 



cpoke 55, 101, 124 
CPU data register 88 
cr 67, 68, 136 
create 60, 132 
creating 

custom banner 32 

dictionary entries 60 

new commands 50 

new logo 33 
ctag! 127 
ctag® 127 
ctrace 88, 143 
cxr! 129 
cxr® 129 

D 

d! 55,101,124 
d# 65, 66 
d? 55, 101, 124 
d@ 55, 101, 125 
dcontext® 130 
debug 91, 145 
debug-off 91, 145 
decimal 45, 65, 135 
default values 26 
defer 60, 62, 132 
defining words 60, 131 
depth 49, 121 

determining SCSI devices 16, 116 

devalias 7, 115 

device 

aliases 7, 15, 103 
node characteristics 4 
pathnames 5 

tree display /traversal 8, 115 
device-end 8, 22, 115 
device-specifier 14, 16 
diag-device 37, 102 
diag-file 24, 37, 102, 117 
diagnostic 

boot from device 37 



OpenBoot Command Reference — August 1994 



boot from file 37 

routines 16 

switch setting 37 
diagnostic test commands 16, 116 
diag-switch? 24, 37, 117 
dictionary of commands 60 
digit 135 
dis 87, 142 

disassembler commands 87, 142 

displaying current parameter settings 27 

displaying registers 88 

dl 81, 142 

dlbin 81, 142 

dload 81, 90, 142 

do 78, 141 

do loops 78 

does> 60, 132 

drop 49, 121 

dump 45, 55, 57, 125 

dup 49, 50, 121 

E 

editing NVRAMRC contents 39 
eeprom utility 29, 33 
eject-floppy 18, 146 
else 74, 140 

emergency keyboard commands 107, 147 

emit 67, 136 

enable! 130 

enable® 130 

endcase 76, 140 

end-code 134 

endof 76, 140 

erase 55, 125 

Ethernet 

displaying the address 21 

testing the controller 19 
eval 80, 81, 141, 142 
execute 80, 141 
exit 80, 141 



exit? 67, 136 
expect 66, 136 

F 

fakeboot 84 
false 73, 139 
FCode interpreter 2 
FCode programs 82,84,85 
fcode-debug? 24,117 
field 60, 132 

file loading commands 81, 142 

fill 55, 125 

find 63, 132 

finish-loop 90, 144 

firmware-version 146 

flag 49, 73, 114 

flip 53, 122 

flush-cache 127 

forget 64, 133 

formatted output commands 136 

Forth 

command format 44 
programs 82,84,85 
reference material xvii 
Source-level Debugger 91, 145 

forth 146 

Forth 83-Standard 54 
Forth Monitor 3 
frame buffer 69 
free-mem 57, 126 
free-virtual 57, 126 
ftrace 92, 146 
full security mode 31 

G 

get-msecs 145 

go 38, 81, 88, 90, 142, 144 

gos 90, 144 
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H 

h# 65, 66, 135 
hardware-revision 24, 117 
help 10, 115 
here 64, 133 
hex 45, 65, 135 
history mechanism 71 
hold 135 
hop 90, 144 
hops 90, 144 

I 

i 78,79,141 
ID PROM 21 
if 74, 140 

immediate 64, 133 
init-program 82, 142 
input 69, 137 
input devices 34 
input-device 24, 34, 70, 117 
interrupt-enable! 129, 130 
interrupt-enable® 129, 130 
io 69, 70, 137 
iomap? 126 
iomap-page 126 
iomap-pages 126 
iommu-ctl! 129 
iommu-ctl@ 129 
iopgmap! 126 
iopgmap® 126 
is 64, 133 

J 

j 79,141 

jmp opcode 87 

K 

key 66, 136 

key? 66, 67, 78, 96, 136 



keyboard 34,70 
keyboard-click? 24, 117 
keymap 24, 117 

L 

L! 55,125 
L, 64, 133 
L? 56, 125 
L@ 54, 56, 125 
La+ 123 
Lal+ 123 
label 134 

last-hardware-update 24, 117 
lbsplit 53, 122 
lcc 68, 137 
leave 79, 141 
left-parse-string 68, 137 
len 48, 114 
lflips 56, 125 

line editor commands 71, 138 

literal 64, 133 

load 82, 142 

load-base 82, 142 

loading/ executing files 

FCode/Binary over serial port A 85 
Forth over serial port A 85 
over Ethernet 82 

over hard disk/floppy/Ethernet 83 
local-mac-address? 24, 117 
long L 49, 114 
loop 79,141 
loops 

conditional 77 

counted 78 
lpeek 56, 102, 125 
lpoke 56, 102, 125 
Is 8,102,115 
lwsplit 53, 122 
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M 

manipulating text strings 68, 137 

map? 57, 126 

map-page 126 

map-pages 126 

map-region 127 

map-regions 127 

map-segments 127 

max 53, 122 

mcr! 129 

mcr@ 129 

memmap 57, 126 

memory 

accessing 54, 124 
mapping primitives 126 
testing 37 

mfg-switch? 24, 37, 117 

mfsr! 129 

mfsr® 129 

min 53, 122 

miscellaneous operations 146 

mod 53, 122 

module-info 146 

move 56, 125 

ms 145 

msafar® 129 

msafsr! 129 

msafsr® 129 

multiprocessor commands 146 

N 

n 49, 114 

n (enter Forth Monitor) 30, 31 
na+ 123 
nal+ 123 
negate 53, 122 
nip 49, 121 

nodefault-bytes 102, 119 
noop 146 
not 53, 122 



null modem cable 94 

number display 65, 134 

numeric output primitives 135 

nvalias 39, 102, 119 

nvedit 38, 39, 41, 119 

nvedit keystroke commands 40, 120 

nvquit 39, 119 

NVRAM 23 

NVRAMRC 

availability 102 

editor commands 39, 119 

nvramrc command 24, 38, 117 

nvrecover 39, 119 

nvrun 39, 120 

nvstore 39, 120 

nvunalias 39, 102, 120 

o 

obio 57, 126 
obmem 57, 126 
oem-banner 24, 32, 117 
oem-banner? 24, 32, 33, 117 
oem-logo 24, 32, 33, 118 
oem-logo? 24, 32, 33, 118 
of 76, 140 
off 56, 125 
old-mode 4, 146 
on 56, 125 
or 53, 123 
origin 64, 133 
output 69, 137 
output devices 34 
output-device 24, 34, 70, 118 
over 50, 121 

P 

p" 68, 137 
pack 68, 137 
pagesize 127 
parentheses 67, 136 
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password 30, 38 
patch 64, 102, 133 
pgmap! 127 
pgmap? 127 
pgmap® 127 
phys 49, 114 
physical address 54 
pick 50, 121 

plug-in device drivers 1 
power cycle 43, 69 
power-on banner 21, 32 
power-on initialization sequence 105 
printenv 26, 27, 119 
probe-scsi 11, 16, 17, 116 
probe-scsi-all 16, 17, 102, 116 
program counter 88 

program execution control commands 80, 
141 

PROM version and date 21 
prompt 75 
pstr 49, 114 
pwd 8, 102, 115 

Q 

quit 80, 141 

R 

r> 50, 121 

r@ 50, 121 

ramforth 146 

reading/ writing registers 

Sun-4C machines 130 

Sun-4D machines 128 

Sun-4M machines 129 
recursive 64, 133 
redirecting input /output 69,137 
repeat 77, 140 
reset 11,22,38,146 
resetting 

parameter defaults 28 



the system 22 
restoring color tables 21 
Restricted Monitor commands 3, 114 
resume 91, 145 
return 90, 144 
returnL 90, 144 
rmap! 127 
rrnap® 127 
roll 50, 121 
romforth 146 
-rot 49, 120 
rot 50, 121 

running extended diagnostics 37 

s 

saving data after a system crash 107 
sbus 57, 126 
sbus-probe-list 24,118 
screen 34, 70 

screen-#columns 24, 34, 118 

screen-#rows 24, 34, 118 

scsi-initiator-id 24, 118 

sd-targets 24, 118 

searching the dictionary 63, 132 

security 

command 30 

full 31 

none 29 

password 30 
security-#badlogins 24, 29, 118 
security-mode 24, 29, 118 
security-password 25, 29, 118 
see 48, 63, 132 
segmentsize 127 
selftest-#megs 25, 37, 118 
serial ports 34, 35, 69 
serr! 130 
serr@ 130 

set-default 26, 28, 119 
set-defaults 26, 28, 119 
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setenv 26, 28, 119 

setenv security-mode exception 38 

set-pc 88,89,143 

setting 

default input/ output devices 35 

firmware security 29 

security password 30 
sfar! 129 
sfar® 129 
sfsr! 129 
sfsr® 129 
show 119 

show-devs 8, 9, 102, 115 
show-sbus 21, 102, 117 
showstack 46, 47, 65, 102, 134 
sift 63, 132 
sifting 63, 132 
sign 135 
size 48, 114 
skip 90, 144 

skip-vme-loopback? 25, 118 

smap! 127 

smap? 127 

smap® 127 

Space 145 

space 67, 136 

spaced 131 

spacec? 131 

spacec® 131 

spaced! 131 

spaced? 102,131 

spaced® 131 

spaceL! 131 

spaceL? 131 

spaceL® 131 

spaces 67, 136 

spacew! 131 

spacew? 131 

spacew® 131 

span 66, 136 



SPARC register commands 88, 143 
specifying auto-booting from Ethernet 36 
stack 

description 46 

diagram 48 

item notation 48, 114 

manipulation commands 49, 120 
state 64, 133 
step 90,144 
stepping 91, 145 
steps 90, 144 
Stop 107,147 
Stop-A 70, 88, 107, 147 
Stop-D 37, 102, 107, 147 
Stop-F 102, 107, 147 
Stop-N 102, 107, 147 
strings, manipulating 68, 137 
struct 60, 132 
st-targets 25, 118 
sunmon-compat? 25, 118 
sverr! 130 
sverr® 130 
swap 50,121 
switch-cpu 146 
symbol table 87 
sync 11,107,146 

system configuration parameters, See 
configuration parameters 

system information display 
commands 117 

T 

terminal 69 
test 16, 103, 116 
test-all 16, 116 
testarea 25, 118 
testing 

clock 16, 20, 116 

diskette drive 16, 18, 116 

memory 16, 19, 116 

network connection 16, 19, 116 
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SBus devices 16, 116 
text input commands 66, 136 
text output commands 67, 136 
then 74, 140 
throw 146 
till 90, 144 
time utilities 145 
TIP problems 96 
TIP window 93,94 
to 33, 88, 89, 143 
Tokenizer 84 
tpe-link-test? 25, 118 
tracing 91, 145 
-trailing 68, 137 
true 73, 139 
ttya 34, 70 

ttya-ignore-cd 25, 118 
ttya-mode 25, 34, 35, 118 
ttya-rts-dtr-off 25, 118 
ttyb 34,70 

ttyb-ignore-cd 25, 118 
ttyb-mode 25, 34, 35, 118 
ttyb-rts-dtr-off 25, 118 
type 67,136 

u 

u*x 53, 123 

u. 65, 134 

u.r 65, 134 

u/mod 53, 123 

u< 73, 139 

u<= 73, 139 

u> 74,139 

u>= 74,139 

u2/ 53,123 

unaligned-L! 56, 125 

unaligned-L@ 56, 125 

unaligned-w! 56, 125 

unaligned-w@ 56, 125 

until 77, 140 



upc 68, 137 

use-nvramrc? 25, 38, 118 

V 

value 60, 61, 132 
variable 60, 62, 132 
version2? 25, 118 
virt 49, 114 
virtual address 54 

w 

w 88, 89, 143 
w! 56,125 
w, 64, 133 
w? 56, 125 
w@ 54, 56, 125 
wa+ 124 
wal+ 124 

watch-clock 16, 20, 116 
watchdog-reboot? 25, 118 
watch-net 16, 20, 103, 116 
ways to enter Forth Monitor 2 
wbsplit 53, 123 
wflip 53,123 
wflips 56, 125 
while 77, 140 
within 74, 139 
wljoin 53, 123 
word 49, 66, 114, 136 
words 8, 10, 45, 63, 115, 132 
wpeek 56, 103, 125 
wpoke 56, 103, 125 

X 

x- 53, 123 
x+ 53,123 
xor 53, 123 
xu/mod 53,123 
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Initial document for Version 2.0 PROMs. 

(Also part of this release: Introduction to Open Boot 2.0 and 

Open Boot 2.0 Command Summary.) 
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August 1994 
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Reader Comments 



We welcome your comments and suggestions to help improve the OpenBoot Command 
Reference, part number: 801-7042-10 and the OpenBoot Quick Reference card, part 
number: 800-5675-11. Please take time to let us know what you think about these 
manuals. 



The information was well documented and easy to follow. 

Strongly Strongly Not 

Agree Agree Disagree Disagree Applicable 

□ □ □ □ □ 

Comments 



The information provided in the manuals was complete. 

Strongly Strongly Not 

Agree Agree Disagree Disagree Applicable 

□ □ □ □ □ 

Comments 



The information I needed was easy to find. 

Strongly Strongly Not 

Agree Agree Disagree Disagree Applicable 

□ □ □ □ □ 

Comments 



The manuals were useful to me. 

Strongly Strongly Not 

Agree Agree Disagree Disagree Applicable 

□ □ □ □ □ 

Comments 



■ Do you have additional comments about the OpenBoot Command Reference and the 
OpenBoot Quick Reference! 
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